The JavaScript API client

Algolia’s JavaScript API client lets you use Algolia’s APIs from your JavaScript app. Compared to using the APIs directly, using the JavaScript API client has these benefits:

• Network retry strategy. The API client automatically retries connecting to another Algolia server, if the connection fails. Thanks to that, using the API clients is covered by Algolia’s SLA.

• Reindexing. The API clients let you reindex your records in a single operation.

• Automatic batching. When you add records to your index, the API client automatically batches your records to make fewer API requests.

Algolia’s Javascript API client is open source. Find the source code on GitHub.

We released a new version of the JavaScript API client in public beta. Read the beta documentation for more information.

You’re reading the documentation for version 4 of the Algolia JavaScript API client. Earlier versions are no longer supported. For upgrading to version 4, see the upgrade guide. You can still access the version 3 documentation.

Quickstart sample app

To download and run a self-contained example, see the JavaScript quickstart on GitHub.

You can use the Algolia JavaScript API client in the browser, and in your backend (Node.js) with the same API.

The JavaScript snippets in the documentation use ES6 syntax. If you want to convert ES6 code to ES5, you can use projects like Babel.js.

For integrating Algolia into your user interface, you should use one of Algolia’s UI libraries instead:

Install the JavaScript API client

The Algolia JavaScript API client requires Node.js version 8.0 or later. The API client supports all popular browsers, including Internet Explorer 11 and newer. Older browsers require polyfills for: Promise, Object.entries, and Object.assign. You can include these polyfills in your HTML with Polyfill.io.

1
<script src="https://polyfill.io/v3/polyfill.min.js?features=Promise%2CObject.entries%2CObject.assign"></script>

Polyfill.io is a third-party CDN. Algolia doesn’t provide support for such third-party services.

Install via npm (recommended)

The recommended method to install the JavaScript API client is via npm.

1
npm install algoliasearch

The npm package includes two versions of the API client:

• algoliasearch-lite: a search-only version in a small bundle
• algoliasearch: the default version for all operations, including indexing, search, and personalization

Both versions come as UMD and ESM modules.

Include from a content delivery network

For quick prototyping or exploration, you can also include the algoliasearch package in a <script> tag from a content delivery network.

1
2
3
4
5
6
7
8
9
10
11
12
13
<!-- search only version -->
<script
  src="https://cdn.jsdelivr.net/npm/algoliasearch@4.22.0/dist/algoliasearch-lite.umd.js"
  integrity="sha256-/2SlAlnMUV7xVQfSkUQTMUG3m2LPXAzbS8I+xybYKwA="
  crossorigin="anonymous"
></script>

<!-- default version -->
<script
  src="https://cdn.jsdelivr.net/npm/algoliasearch@4.22.0/dist/algoliasearch.umd.js"
  integrity="sha256-09Su4oLnpiFZJWk1HPm+P8R5PsH8IwHHmYatWY5q4w4="
  crossorigin="anonymous"
></script>

If you’re using JavaScript (ES6) modules, use these packages:

1
2
3
4
5
6
7
<script type="module">
// search only version
import algoliasearch from 'https://cdn.jsdelivr.net/npm/algoliasearch@4.22.0/dist/algoliasearch-lite.esm.browser.js';

// default version
import algoliasearch from 'https://cdn.jsdelivr.net/npm/algoliasearch@4.22.0/dist/algoliasearch.esm.browser.js';
</script>

jsDelivr is a third-party CDN. Algolia can’t provide support for such third-party services.

Test your installation

If you haven’t already, create an Algolia account and create a new Algolia app to get started.

To test whether you can connect to Algolia, run a simple program that adds a record to a new index, searches the index, and print the results.

1. Copy the following code sample into a text editor. If you’re signed in, the code samples below show your Algolia application ID. If you’re not signed in, replace YourApplicationID with your Algolia application ID and YourWriteAPIKey with your Write API Key. You can find both in your Algolia account.

   JavaScript

   Copy

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   // hello_algolia.js
   const algoliasearch = require('algoliasearch')
   
   // Connect and authenticate with your Algolia app
   const client = algoliasearch('YourApplicationID', 'YourWriteAPIKey')
   
   // Create a new index and add a record
   const index = client.initIndex('test_index')
   const record = { objectID: 1, name: 'test_record' }
   index.saveObject(record).wait()
   
   // Search the index and print the results
   index
     .search('test_record')
     .then(({ hits }) => console.log(hits[0]))
   

2. Save the file as hello_algolia.js. Go to the directory with the file you just created and run inside a terminal:

   Shell

   Copy

   1
   node hello_algolia.js
   

3. If the program ran successfully, you should see:

   Copy

   1
   2
   3
   4
   5
   6
   {
      name: 'test_record',
      objectID: '1',
      _highlightResult: {
      ...
   }
   

You can inspect your index now in the Algolia dashboard.

Next steps

Now you can interact with the Algolia Search API, you can look at the available methods, for example, for search or indexing.

Other APIs, for example for Algolia Recommend or Analytics, come with their own clients. To get an overview, see Initialize the API client.