node package manager

algoliasearch

AlgoliaSearch API JavaScript client

Algolia Search API Client for JavaScript

Algolia Search is a hosted full-text, numerical, and faceted search engine capable of delivering realtime results from the first keystroke.

The JavaScript client lets you use the Algolia Search API on the frontend (browsers) or on the backend (Node.js) with the same API.

The backend (Node.js) API can be used to index your data using your Algolia admin API keys.

Our JavaScript library is UMD compatible, you can use it with any module loader.

When not using any module loader, it will export an algoliasearch function in the window object.

Getting Started

  1. Setup
  1. Quick Start
  1. Client options
  2. Callback convention
  3. Promises
  4. Request strategy
  5. Cache
  6. Proxy support
  7. Keep-alive
  8. Guides & Tutorials
  9. Old JavaScript clients

Commands Reference

  1. Add a new object
  2. Update an object
  3. Search
  4. Multiple queries
  5. Get an object
  6. Delete an object
  7. Delete by query
  8. Index settings
  9. List indices
  10. Delete an index
  11. Clear an index
  12. Wait indexing
  13. Batch writes
  14. Copy / Move an index
  15. Backup / Export an index
  16. API Keys
  17. Logs

Setup

To setup your project, follow these steps:

You can either use a package manager like npm or include a <script> tag.

npm install algoliasearch --save

We are browserifyable and webpack friendly.

bower install algoliasearch -S
Recommended: jsDelivr.com

jsDelivr is a global CDN delivery for JavaScript libraries.

To include the latest releases and all upcoming features and patches, use this:

<script src="//cdn.jsdelivr.net/algoliasearch/3/algoliasearch.min.js"></script>

We recommend using jsDelivr, but algoliasearch is also available at:

npm install algoliasearch --save
var algoliasearch = require('algoliasearch');
var client = algoliasearch('applicationID', 'apiKey');
var index = client.initIndex('indexName');
index.search('something', function searchDone(errcontent) {
  console.log(err, content);
});
npm install algoliasearch --save
var algoliasearch = require('algoliasearch');
var client = algoliasearch('applicationID', 'apiKey');
var index = client.initIndex('indexName');
index.search('something', function searchDone(errcontent) {
  console.log(err, content);
});

Parse.com

curl https://raw.githubusercontent.com/algolia/algoliasearch-client-js/master/dist/algoliasearch.parse.js -o /your/parse/project/cloud/algoliasearch.parse.js

In cloud/main.js for example:

var algoliasearch = require('cloud/algoliasearch.parse.js');
var client = algoliasearch('latency', '6be0576ff61c053d5f9a3225e2a90f76');
var index = client.initIndex('contacts');
 
Parse.Cloud.define("hello", function(requestresponse) {
  index.search('Atlenta', function(errresults) {
    if (err) {
      throw err;
    }
 
    response.success('We got ' + results.nbHits + ' results');
  });
});
npm install algoliasearch --save
var algoliasearch = require('algoliasearch/reactnative');
var client = algoliasearch('applicationID', 'apiKey');
var index = client.initIndex('indexName');
index.search('something', function searchDone(errcontent) {
  console.log(err, content);
});

To build your frontend search experience, also check out our examples and guides.

<script src="//cdn.jsdelivr.net/algoliasearch/3/algoliasearch.min.js"></script>
<script>
  var client = algoliasearch('ApplicationID', 'apiKey');
  var index = client.initIndex('indexName');
 
  index.search('an example', function searchDone(errcontent) {
    console.log(err, content)
  });
 
  index.search('another example')
    .then(function searchSuccess(content) {
      console.log(content);
    })
    .catch(function searchFailure(err) {
      console.error(err);
    });
</script> 

We provide a specific jQuery build that will use jQuery.ajax.

It can be used with callbacks or jQuery promises.

<script src="//cdn.jsdelivr.net/jquery/2.1.3/jquery.min.js"></script>
<script src="//cdn.jsdelivr.net/algoliasearch/3/algoliasearch.jquery.min.js"></script>
<script>
  var client = $.algolia.Client('ApplicationID', 'apiKey');
  var index = client.initIndex('indexName');
  index.search('something', function searchDone(errcontent) {
    console.log(err, content)
  });
</script> 

We provide a specific AngularJS build that is using the $http service.

It can be used with callbacks or AngularJS promises.

<script src="//cdn.jsdelivr.net/angularjs/1.3.14/angular.min.js"></script>
<script src="//cdn.jsdelivr.net/algoliasearch/3/algoliasearch.angular.min.js"></script>
<script>
  angular
    .module('myapp', ['algoliasearch'])
    .controller('SearchCtrl', ['$scope', 'algolia', function($scopealgolia) {
      $scope.query = '';
      $scope.hits = [];
      var client = algolia.Client('ApplicationID', 'apiKey');
      var index = client.initIndex('indexName');
      index.search('something')
        .then(function searchSuccess(content) {
          console.log(content);
        }, function searchFailure(err) {
          console.log(err);
        });
    }]);
</script> 

In 30 seconds, this quick start tutorial will show you how to index and search objects.

Without any prior configuration, you can start indexing 500 contacts in the contacts index using the following code:

var index = client.initIndex('contacts');
var contactsJSON = require('./contacts.json');
 
index.addObjects(contactsJSON, function(errcontent) {
  if (err) {
    console.error(err);
  }
});

You can now search for contacts using firstname, lastname, company, etc. (even with typos):

// firstname 
index.search('jimmie', function(errcontent) {
  console.log(content.hits);
});
 
// firstname with typo 
index.search('jimie', function(errcontent) {
  console.log(content.hits);
});
 
// a company 
index.search('california paint', function(errcontent) {
  console.log(content.hits);
});
 
// a firstname & company 
index.search('jimmie paint', function(errcontent) {
  console.log(content.hits);
});

Settings can be customized to tune the search behavior. For example, you can add a custom sort by number of followers to the already great built-in relevance:

index.setSettings({
  'customRanking': ['desc(followers)']
}, function(errcontent) {
  console.log(content);
});

You can also configure the list of attributes you want to index by order of importance (first = most important):

index.setSettings({
  'attributesToIndex': [
    'lastname',
    'firstname',
    'company',
    'email',
    'city',
    'address'
  ]
}, function(errcontent) {
  console.log(content);
});

Since the engine is designed to suggest results as you type, you'll generally search by prefix. In this case the order of attributes is very important to decide which hit is the best:

index.search('or', function(errcontent) {
  console.log(content.hits);
});
 
index.search('jim', function(errcontent) {
  console.log(content.hits);
});

In most situations, there is no need to tune the options. We provide this list to be transparent with our users.

  • timeout (Number) timeout for requests to our servers, in milliseconds
    • in Node.js this is an inactivity timeout. Defaults to 15s
    • in the browser, this is a global timeout. Defaults to 2s (incremental)
  • protocol (String) protocol to use when communicating with algolia
    • in the browser, we use the page protocol by default
    • in Node.js it's https by default
    • possible values: 'http:', 'https:'
  • hosts.read ([String]) array of read hosts to use to call Algolia servers, computed automatically
  • hosts.write ([String]) array of write hosts to use to call Algolia servers, computed automatically
  • httpAgent (HttpAgent) node-only Node.js httpAgent instance to use when communicating with Algolia servers.

To pass an option, use:

var client = algoliasearch(applicationId, apiKey, {
  timeout: 4000
})

Every API call takes a callback as last parameter. This callback will then be called with two arguments:

  1. error: null or an Error object. More info on the error can be find in error.message.
  2. content: the object containing the answer from the server, it's a JavaScript object

If you do not provide a callback, you will get a promise (but never both).

Promises are the native Promise implementation.

We use jakearchibald/es6-promise as a polyfill when needed.

The request strategy used by the JavaScript client includes:

Connections are always keep-alive.

Browser only

To avoid performing the same API calls twice search results will be stored in a cache that will be tied to your JavaScript client and index objects.

It's particularly useful when your users are deleting characters or words from the current query but has a chance of ending up with outdated results if the page isn't refreshed for some time.

If at any point you want to clear the cache, just do this:

// clear the queries cache 
index.clearCache();
 
// if you're performing multi-queries using the API client instead of the index 
// you'll need to use the following code 
client.clearCache();

Node.js only

If you are behind a proxy, just set HTTP_PROXY or HTTPS_PROXY environment variables before starting your Node.js program.

HTTP_PROXY=http://someproxy.com:9320 node main.js

Node.js only

Keep-alive is activated by default.

Because of the nature of keepalive connections, your process will hang even if you do not do any more command using the client.

To fix this, we expose a client.destroy() method that will terminate all remaining alive connections.

You should call this method when you are finished working with the AlgoliaSearch API. So that your process will exit gently.

Note: keep-alive is still always activated in browsers, this is a native behavior of browsers.

Guides & Tutorials

Check our online guides:

Old JavaScript clients

In April 2015, we released the V3 of our JavaScript client (the one you are looking at) able to work in Node.js and the browser.

If you were using our browser version (V2), read the migration guide

If you were using our Node.js version (V1, npm algolia-search), read the migration guide

Add a new object to the Index

Each entry in an index has a unique identifier called objectID. There are two ways to add en entry to the index:

  1. Using automatic objectID assignment. You will be able to access it in the answer.
  2. Supplying your own objectID.

You don't need to explicitly create an index, it will be automatically created the first time you add an object. Objects are schema less so you don't need any configuration to start indexing. If you wish to configure things, the settings section provides details about advanced settings.

Example with automatic objectID assignment:

index.addObject({
  firstname: 'Jimmie',
  lastname: 'Barninger'
}, function(errcontent) {
  console.log('objectID=' + content.objectID);
});

Example with manual objectID assignment:

index.addObject({
  firstname: 'Jimmie',
  lastname: 'Barninger'
}, 'myID', function(errcontent) {
  console.log('objectID=' + content.objectID);
});

Update an existing object in the Index

You have three options when updating an existing object:

  1. Replace all its attributes.
  2. Replace only some attributes.
  3. Apply an operation to some attributes.

Example on how to replace all attributes of an existing object:

index.saveObject({
  firstname: 'Jimmie',
  lastname: 'Barninger',
  city: 'New York',
  objectID: 'myID'
}, function(errcontent) {
  console.log(content);
});

You have many ways to update an object's attributes:

  1. Set the attribute value
  2. Add a string or number element to an array
  3. Remove an element from an array
  4. Add a string or number element to an array if it doesn't exist
  5. Increment an attribute
  6. Decrement an attribute

Example to update only the city attribute of an existing object:

index.partialUpdateObject({
  city: 'San Francisco',
  objectID: 'myID'
}, function(errcontent) {
  console.log(content);
});

Example to add a tag:

index.partialUpdateObject({
  _tags: {
    value: 'MyTag',
    _operation: 'Add'
  },
  objectID: 'myID'
}, function(errcontent) {
  console.log(content);
});

Example to remove a tag:

index.partialUpdateObject({
  _tags: {
    value: 'MyTag',
    _operation:'Remove'
  },
  objectID: 'myID'
}, function(errcontent) {
  console.log(content);
});

Example to add a tag if it doesn't exist:

index.partialUpdateObject({
  _tags: {
    value: 'MyTag',
    _operation: 'AddUnique'
  },
  objectID: 'myID'
}, function(errcontent) {
  console.log(content);
});

Example to increment a numeric value:

index.partialUpdateObject({
  price: {
    value: 42,
    _operation: 'Increment'
  },
  objectID: 'myID'
}, function(errcontent) {
  console.log(content);
});

Note: Here we are incrementing the value by 42. To increment just by one, put value:1.

Example to decrement a numeric value:

index.partialUpdateObject({
  price: {
    value: 42,
    _operation: 'Decrement'
  },
  objectID: 'myID'
}, function(errcontent) {
  console.log(content);
});

Note: Here we are decrementing the value by 42. To decrement just by one, put value:1.

Search

To perform a search, you only need to initialize the index and perform a call to the search function.

The search query allows only to retrieve 1000 hits, if you need to retrieve more than 1000 hits for seo, you can use Backup / Retrieve all index content

var client = algoliasearch('ApplicationID', 'Search-Only-API-Key');
var index = client.initIndex('indexName');
 
// only query string 
index.search('query string', function searchDone(errcontent) {
  if (err) {
    console.error(err);
    return;
  }
 
  for (var h in content.hits) {
    console.log('Hit(' + content.hits[h].objectID + '): ' + content.hits[h].toString());
  }
});
 
// with params 
index.search('query string', {
  attributesToRetrieve: ['firstname', 'lastname'],
  hitsPerPage: 50
}, function searchDone(errcontent) {
  if (err) {
    console.error(err);
    return;
  }
 
  for (var h in content.hits) {
    console.log('Hit(' + content.hits[h].objectID + '): ' + content.hits[h].toString());
  }
});

The server response will look like:

{
  "hits": [
    {
      "firstname": "Jimmie",
      "lastname": "Barninger",
      "objectID": "433",
      "_highlightResult": {
        "firstname": {
          "value": "<em>Jimmie</em>",
          "matchLevel": "partial"
        },
        "lastname": {
          "value": "Barninger",
          "matchLevel": "none"
        },
        "company": {
          "value": "California <em>Paint</em> & Wlpaper Str",
          "matchLevel": "partial"
        }
      }
    }
  ],
  "page": 0,
  "nbHits": 1,
  "nbPages": 1,
  "hitsPerPage": 20,
  "processingTimeMS": 1,
  "query": "jimmie paint",
  "params": "query=jimmie+paint&attributesToRetrieve=firstname,lastname&hitsPerPage=50"
}

You can use the following optional arguments:

<tr>
  <td valign='top'>
    <div class='client-readme-param-container'>
      <div class='client-readme-param-container-inner'>
        <div class='client-readme-param-name'><code>query</code></div>
        <div class="client-readme-param-meta"><div><em>Type: <strong>string</strong></em></div></div>
      </div>
    </div>
  </td>
  <td class='client-readme-param-content'>
    <p>The instant search query string, used to set the string you want to search in your index. If no query parameter is set, the textual search will match with all the objects.</p>

  </td>
</tr>



<tr>
  <td valign='top'>
    <div class='client-readme-param-container'>
      <div class='client-readme-param-container-inner'>
        <div class='client-readme-param-name'><code>queryType</code></div>
        <div class="client-readme-param-meta"><div><em>Default: <strong>prefixLast</strong></em></div></div>
      </div>
    </div>
  </td>
  <td class='client-readme-param-content'>
    <p>Selects how the query words are interpreted. It can be one of the following values:</p>
  • prefixAll: All query words are interpreted as prefixes. This option is not recommended.
  • prefixLast: Only the last word is interpreted as a prefix (default behavior).
  • prefixNone: No query word is interpreted as a prefix. This option is not recommended.
  </td>
</tr>



<tr>
  <td valign='top'>
    <div class='client-readme-param-container'>
      <div class='client-readme-param-container-inner'>
        <div class='client-readme-param-name'><code>removeWordsIfNoResults</code></div>
        <div class="client-readme-param-meta"><div><em>Default: <strong>none</strong></em></div></div>
      </div>
    </div>
  </td>
  <td class='client-readme-param-content'>
    <p>This option is used to select a strategy in order to avoid having an empty result page. There are three different options:</p>
  • lastWords: When a query does not return any results, the last word will be added as optional. The process is repeated with n-1 word, n-2 word, ... until there are results.
  • firstWords: When a query does not return any results, the first word will be added as optional. The process is repeated with second word, third word, ... until there are results.
  • allOptional: When a query does not return any results, a second trial will be made with all words as optional. This is equivalent to transforming the AND operand between query terms to an OR operand.
  • none: No specific processing is done when a query does not return any results (default behavior).
  </td>
</tr>



<tr>
  <td valign='top'>
    <div class='client-readme-param-container'>
      <div class='client-readme-param-container-inner'>
        <div class='client-readme-param-name'><code>minWordSizefor1Typo</code></div>
        <div class="client-readme-param-meta"><div><em>Type: <strong>number</strong></em></div><div><em>Default: <strong>4</strong></em></div></div>
      </div>
    </div>
  </td>
  <td class='client-readme-param-content'>
    <p>The minimum number of characters in a query word to accept one typo in this word.<br/>Defaults to 4.</p>

  </td>
</tr>



<tr>
  <td valign='top'>
    <div class='client-readme-param-container'>
      <div class='client-readme-param-container-inner'>
        <div class='client-readme-param-name'><code>minWordSizefor2Typos</code></div>
        <div class="client-readme-param-meta"><div><em>Type: <strong>number</strong></em></div><div><em>Default: <strong>8</strong></em></div></div>
      </div>
    </div>
  </td>
  <td class='client-readme-param-content'>
    <p>The minimum number of characters in a query word to accept two typos in this word.<br/>Defaults to 8.</p>

  </td>
</tr>



<tr>
  <td valign='top'>
    <div class='client-readme-param-container'>
      <div class='client-readme-param-container-inner'>
        <div class='client-readme-param-name'><code>typoTolerance</code></div>
        <div class="client-readme-param-meta"><div><em>Default: <strong>true</strong></em></div></div>
      </div>
    </div>
  </td>
  <td class='client-readme-param-content'>
    <p>This option allows you to control the number of typos allowed in the result set:</p>
  • true: The typo tolerance is enabled and all matching hits are retrieved (default behavior).
  • false: The typo tolerance is disabled. All results with typos will be hidden.
  • min: Only keep results with the minimum number of typos. For example, if one result matches without typos, then all results with typos will be hidden.
  • strict: Hits matching with 2 typos are not retrieved if there are some matching without typos.
  </td>
</tr>



<tr>
  <td valign='top'>
    <div class='client-readme-param-container'>
      <div class='client-readme-param-container-inner'>
        <div class='client-readme-param-name'><code>allowTyposOnNumericTokens</code></div>
        <div class="client-readme-param-meta"><div><em>Default: <strong>true</strong></em></div></div>
      </div>
    </div>
  </td>
  <td class='client-readme-param-content'>
    <p>If set to false, disables typo tolerance on numeric tokens (numbers). Defaults to true.</p>

  </td>
</tr>



<tr>
  <td valign='top'>
    <div class='client-readme-param-container'>
      <div class='client-readme-param-container-inner'>
        <div class='client-readme-param-name'><code>ignorePlural</code></div>
        <div class="client-readme-param-meta"><div><em>Default: <strong>false</strong></em></div></div>
      </div>
    </div>
  </td>
  <td class='client-readme-param-content'>
    <p>If set to true, plural won&#39;t be considered as a typo. For example, car and cars, or foot and feet will be considered as equivalent. Defaults to false.</p>

  </td>
</tr>



<tr>
  <td valign='top'>
    <div class='client-readme-param-container'>
      <div class='client-readme-param-container-inner'>
        <div class='client-readme-param-name'><code>disableTypoToleranceOnAttributes</code></div>
        <div class="client-readme-param-meta"><div><em>Default: <strong>[]</strong></em></div></div>
      </div>
    </div>
  </td>
  <td class='client-readme-param-content'>
    <p>List of attributes on which you want to disable typo tolerance (must be a subset of the <code>attributesToIndex</code> index setting). Attributes are separated with a comma such as <code>&quot;name,address&quot;</code>. You can also use JSON string array encoding such as <code>encodeURIComponent(&quot;[\&quot;name\&quot;,\&quot;address\&quot;]&quot;)</code>. By default, this list is empty.</p>

  </td>
</tr>



<tr>
  <td valign='top'>
    <div class='client-readme-param-container'>
      <div class='client-readme-param-container-inner'>
        <div class='client-readme-param-name'><code>restrictSearchableAttributes</code></div>
        <div class="client-readme-param-meta"><div><em>Default: <strong>attributesToIndex</strong></em></div></div>
      </div>
    </div>
  </td>
  <td class='client-readme-param-content'>
    <p>List of attributes you want to use for textual search (must be a subset of the <code>attributesToIndex</code> index setting). Attributes are separated with a comma such as <code>&quot;name,address&quot;</code>. You can also use JSON string array encoding such as <code>encodeURIComponent(&quot;[\&quot;name\&quot;,\&quot;address\&quot;]&quot;)</code>. By default, all attributes specified in the <code>attributesToIndex</code> settings are used to search.</p>

  </td>
</tr>



<tr>
  <td valign='top'>
    <div class='client-readme-param-container'>
      <div class='client-readme-param-container-inner'>
        <div class='client-readme-param-name'><code>removeStopWords</code></div>
        <div class="client-readme-param-meta"><div><em>Default: <strong>false</strong></em></div></div>
      </div>
    </div>
  </td>
  <td class='client-readme-param-content'>
    <p>Remove the stop words from query before executing it. Defaults to false. Contains a list of stop words from 41 languages (Arabic, Armenian, Basque, Bengali, Brazilian, Bulgarian, Catalan, Chinese, Czech, Danish, Dutch, English, Finnish, French, Galician, German, Greek, Hindi, Hungarian, Indonesian, Irish, Italian, Japanese, Korean, Kurdish, Latvian, Lithuanian, Marathi, Norwegian, Persian, Polish, Portugese, Romanian, Russian, Slovak, Spanish, Swedish, Thai, Turkish, Ukranian, Urdu). In most use-cases, we don&#39;t recommend enabling this option.</p>

  </td>
</tr>



<tr>
  <td valign='top'>
    <div class='client-readme-param-container'>
      <div class='client-readme-param-container-inner'>
        <div class='client-readme-param-name'><code>advancedSyntax</code></div>
        <div class="client-readme-param-meta"><div><em>Default: <strong>0 (false)</strong></em></div></div>
      </div>
    </div>
  </td>
  <td class='client-readme-param-content'>
    <p>Enables the advanced query syntax. Defaults to 0 (false).</p>
  • Phrase query: A phrase query defines a particular sequence of terms. A phrase query is built by Algolia's query parser for words surrounded by ". For example, "search engine" will retrieve records having search next to engine only. Typo tolerance is disabled on phrase queries.
  • Prohibit operator: The prohibit operator excludes records that contain the term after the - symbol. For example, search -engine will retrieve records containing search but not engine.
  </td>
</tr>



<tr>
  <td valign='top'>
    <div class='client-readme-param-container'>
      <div class='client-readme-param-container-inner'>
        <div class='client-readme-param-name'><code>analytics</code></div>
        <div class="client-readme-param-meta"><div><em>Default: <strong>true</strong></em></div></div>
      </div>
    </div>
  </td>
  <td class='client-readme-param-content'>
    <p>If set to false, this query will not be taken into account in the analytics feature. Defaults to true.</p>

  </td>
</tr>



<tr>
  <td valign='top'>
    <div class='client-readme-param-container'>
      <div class='client-readme-param-container-inner'>
        <div class='client-readme-param-name'><code>synonyms</code></div>
        <div class="client-readme-param-meta"><div><em>Default: <strong>true</strong></em></div></div>
      </div>
    </div>
  </td>
  <td class='client-readme-param-content'>
    <p>If set to false, this query will not use synonyms defined in the configuration. Defaults to true.</p>

  </td>
</tr>



<tr>
  <td valign='top'>
    <div class='client-readme-param-container'>
      <div class='client-readme-param-container-inner'>
        <div class='client-readme-param-name'><code>replaceSynonymsInHighlight</code></div>
        <div class="client-readme-param-meta"><div><em>Default: <strong>true</strong></em></div></div>
      </div>
    </div>
  </td>
  <td class='client-readme-param-content'>
    <p>If set to false, words matched via synonym expansion will not be replaced by the matched synonym in the highlight results. Defaults to true.</p>

  </td>
</tr>


  
<tr>
  <td valign='top'>
    <div class='client-readme-param-container'>
      <div class='client-readme-param-container-inner'>
        <div class='client-readme-param-name'><code>optionalWords</code></div>
        <div class="client-readme-param-meta"><div><em>Default: <strong>[]</strong></em></div></div>
      </div>
    </div>
  </td>
  <td class='client-readme-param-content'>
    <p>A string that contains the comma separated list of words that should be considered as optional when found in the query.</p>

  </td>
</tr>
<tr>
  <td valign='top'>
    <div class='client-readme-param-container'>
      <div class='client-readme-param-container-inner'>
        <div class='client-readme-param-name'><code>page</code></div>
        <div class="client-readme-param-meta"><div><em>Type: <strong>integer</strong></em></div><div><em>Default: <strong>0</strong></em></div></div>
      </div>
    </div>
  </td>
  <td class='client-readme-param-content'>
    <p>Pagination parameter used to select the page to retrieve.<br/>Page is zero based and defaults to 0. Thus, to retrieve the 10th page you need to set <code>page=9</code>.</p>

  </td>
</tr>



<tr>
  <td valign='top'>
    <div class='client-readme-param-container'>
      <div class='client-readme-param-container-inner'>
        <div class='client-readme-param-name'><code>hitsPerPage</code></div>
        <div class="client-readme-param-meta"><div><em>Type: <strong>integer</strong></em></div><div><em>Default: <strong>20</strong></em></div></div>
      </div>
    </div>
  </td>
  <td class='client-readme-param-content'>
    <p>Pagination parameter used to select the number of hits per page. Defaults to 20.</p>

  </td>
</tr>
<tr>
  <td valign='top'>
    <div class='client-readme-param-container'>
      <div class='client-readme-param-container-inner'>
        <div class='client-readme-param-name'><code>aroundLatLng</code></div>
        
      </div>
    </div>
  </td>
  <td class='client-readme-param-content'>
    <p>Search for entries around a given latitude/longitude (specified as two floats separated by a comma).<br/>For example, <code>aroundLatLng=47.316669,5.016670</code>.</p>

By default the maximum distance is automatically guessed based on the density of the area but you can specify it manually in meters with the aroundRadius parameter. The precision for ranking can be set with aroundPrecision parameter. For example, if you set aroundPrecision=100, the distances will be considered by ranges of 100m, for example all distances 0 and 100m will be considered as identical for the "geo" ranking parameter.

When aroundRadius is not set, the radius is computed automatically using the density of the area, you can retrieve the computed radius in the automaticRadius attribute of the answer, you can also use the minimumAroundRadius query parameter to specify a minimum radius in meters for the automatic computation of aroundRadius.

At indexing, you should specify geoloc of an object with the _geoloc attribute (in the form "_geoloc":{"lat":48.853409, "lng":2.348800} or "_geoloc":[{"lat":48.853409, "lng":2.348800},{"lat":48.547456, "lng":2.972075}] if you have several geo-locations in your record).

  </td>
</tr>






<tr>
  <td valign='top'>
    <div class='client-readme-param-container'>
      <div class='client-readme-param-container-inner'>
        <div class='client-readme-param-name'><code>aroundLatLngViaIP</code></div>
        
      </div>
    </div>
  </td>
  <td class='client-readme-param-content'>
    <p>Search for entries around a given latitude/longitude automatically computed from user IP address.<br/>To enable it, use <code>aroundLatLngViaIP=true</code>.</p>

You can specify the maximum distance in meters with the aroundRadius parameter and the precision for ranking with aroundPrecision. For example, if you set aroundPrecision=100, two objects that are in the range 0-99m will be considered as identical in the ranking for the "geo" ranking parameter (same for 100-199, 200-299, ... ranges).

At indexing, you should specify the geo location of an object with the _geoloc attribute in the form {"_geoloc":{"lat":48.853409, "lng":2.348800}}.

  </td>
</tr>





<tr>
  <td valign='top'>
    <div class='client-readme-param-container'>
      <div class='client-readme-param-container-inner'>
        <div class='client-readme-param-name'><code>insideBoundingBox</code></div>
        
      </div>
    </div>
  </td>
  <td class='client-readme-param-content'>
    <p>Search entries inside a given area defined by the two extreme points of a rectangle (defined by 4 floats: p1Lat,p1Lng,p2Lat,p2Lng).<br/>For example, <code>insideBoundingBox=47.3165,4.9665,47.3424,5.0201</code>).<br/>At indexing, you should specify geoloc of an object with the _geoloc attribute (in the form <code>&quot;_geoloc&quot;:{&quot;lat&quot;:48.853409, &quot;lng&quot;:2.348800}</code> or <code>&quot;_geoloc&quot;:[{&quot;lat&quot;:48.853409, &quot;lng&quot;:2.348800},{&quot;lat&quot;:48.547456, &quot;lng&quot;:2.972075}]</code> if you have several geo-locations in your record). You can use several bounding boxes (OR) by passing more than 4 values. For example instead of having 4 values you can pass 8 to search inside the UNION of two bounding boxes.</p>

  </td>
</tr>



<tr>
  <td valign='top'>
    <div class='client-readme-param-container'>
      <div class='client-readme-param-container-inner'>
        <div class='client-readme-param-name'><code>insidePolygon</code></div>
        
      </div>
    </div>
  </td>
  <td class='client-readme-param-content'>
    <p>Search entries inside a given area defined by a set of points (defined by a minimum of 6 floats: p1Lat,p1Lng,p2Lat,p2Lng,p3Lat,p3Long).<br/>For example <code>InsidePolygon=47.3165,4.9665,47.3424,5.0201,47.32,4.98</code>).<br/>At indexing, you should specify geoloc of an object with the _geoloc attribute (in the form <code>&quot;_geoloc&quot;:{&quot;lat&quot;:48.853409, &quot;lng&quot;:2.348800}</code> or <code>&quot;_geoloc&quot;:[{&quot;lat&quot;:48.853409, &quot;lng&quot;:2.348800},{&quot;lat&quot;:48.547456, &quot;lng&quot;:2.972075}]</code> if you have several geo-locations in your record).</p>

  </td>
</tr>
<tr>
  <td valign='top'>
    <div class='client-readme-param-container'>
      <div class='client-readme-param-container-inner'>
        <div class='client-readme-param-name'><code>attributesToRetrieve</code></div>
        
      </div>
    </div>
  </td>
  <td class='client-readme-param-content'>
    <p>A string that contains the list of attributes you want to retrieve in order to minimize the size of the JSON answer.</p>

Attributes are separated with a comma (for example "name,address"). You can also use a string array encoding (for example ["name","address"] ). By default, all attributes are retrieved. You can also use * to retrieve all values when an attributesToRetrieve setting is specified for your index.

  </td>
</tr>



<tr>
  <td valign='top'>
    <div class='client-readme-param-container'>
      <div class='client-readme-param-container-inner'>
        <div class='client-readme-param-name'><code>attributesToHighlight</code></div>
        
      </div>
    </div>
  </td>
  <td class='client-readme-param-content'>
    <p>A string that contains the list of attributes you want to highlight according to the query. Attributes are separated by commas. You can also use a string array encoding (for example <code>[&quot;name&quot;,&quot;address&quot;]</code>). If an attribute has no match for the query, the raw value is returned. By default, all indexed attributes are highlighted. You can use <code>*</code> if you want to highlight all attributes. A matchLevel is returned for each highlighted attribute and can contain:</p>
  • full: If all the query terms were found in the attribute.
  • partial: If only some of the query terms were found.
  • none: If none of the query terms were found.
  </td>
</tr>



<tr>
  <td valign='top'>
    <div class='client-readme-param-container'>
      <div class='client-readme-param-container-inner'>
        <div class='client-readme-param-name'><code>attributesToSnippet</code></div>
        
      </div>
    </div>
  </td>
  <td class='client-readme-param-content'>
    <p>A string that contains the list of attributes to snippet alongside the number of words to return (syntax is <code>attributeName:nbWords</code>). Attributes are separated by commas (Example: <code>attributesToSnippet=name:10,content:10</code>).</p>

You can also use a string array encoding (Example: attributesToSnippet: ["name:10","content:10"]). By default, no snippet is computed.

  </td>
</tr>



<tr>
  <td valign='top'>
    <div class='client-readme-param-container'>
      <div class='client-readme-param-container-inner'>
        <div class='client-readme-param-name'><code>getRankingInfo</code></div>
        
      </div>
    </div>
  </td>
  <td class='client-readme-param-content'>
    <p>If set to 1, the result hits will contain ranking information in the <code>_rankingInfo</code> attribute.</p>

  </td>
</tr>



<tr>
  <td valign='top'>
    <div class='client-readme-param-container'>
      <div class='client-readme-param-container-inner'>
        <div class='client-readme-param-name'><code>highlightPreTag</code></div>
        <div class="client-readme-param-meta"><div><em>Type: <strong>string</strong></em></div><div><em>Default: <strong>&lt;em&gt;</strong></em></div></div>
      </div>
    </div>
  </td>
  <td class='client-readme-param-content'>
    <p>Specify the string that is inserted before the highlighted parts in the query result (defaults to <code>&lt;em&gt;</code>).</p>

  </td>
</tr>



<tr>
  <td valign='top'>
    <div class='client-readme-param-container'>
      <div class='client-readme-param-container-inner'>
        <div class='client-readme-param-name'><code>highlightPostTag</code></div>
        <div class="client-readme-param-meta"><div><em>Type: <strong>string</strong></em></div><div><em>Default: <strong>&lt;/em&gt;</strong></em></div></div>
      </div>
    </div>
  </td>
  <td class='client-readme-param-content'>
    <p>Specify the string that is inserted after the highlighted parts in the query result (defaults to <code>&lt;/em&gt;</code>)</p>

  </td>
</tr>



<tr>
  <td valign='top'>
    <div class='client-readme-param-container'>
      <div class='client-readme-param-container-inner'>
        <div class='client-readme-param-name'><code>snippetEllipsisText</code></div>
        <div class="client-readme-param-meta"><div><em>Type: <strong>string</strong></em></div><div><em>Default: <strong>''</strong></em></div></div>
      </div>
    </div>
  </td>
  <td class='client-readme-param-content'>
    <p>String used as an ellipsis indicator when a snippet is truncated. Defaults to an empty string for all accounts created before 10/2/2016, and to <code>…</code> (UTF-8 U+2026) for accounts created after that date.</p>

  </td>
</tr>
<tr>
  <td valign='top'>
    <div class='client-readme-param-container'>
      <div class='client-readme-param-container-inner'>
        <div class='client-readme-param-name'><code>numericFilters</code></div>
        
      </div>
    </div>
  </td>
  <td class='client-readme-param-content'>
    <p>A string that contains the comma separated list of numeric filters you want to apply. The filter syntax is <code>attributeName</code> followed by <code>operand</code> followed by <code>value</code>. Supported operands are <code>&lt;</code>, <code>&lt;=</code>, <code>=</code>, <code>&gt;</code> and <code>&gt;=</code>.</p>

  </td>
</tr>

You can easily perform range queries via the : operator. This is equivalent to combining a >= and <= operand. For example, numericFilters=price:10 to 1000.

You can also mix OR and AND operators. The OR operator is defined with a parenthesis syntax. For example, (code=1 AND (price:[0-100] OR price:[1000-2000])) translates to encodeURIComponent("code=1,(price:0 to 100,price:1000 to 2000)").

You can also use a string array encoding (for example numericFilters: ["price>100","price<1000"]).

<tr>
  <td valign='top'>
    <div class='client-readme-param-container'>
      <div class='client-readme-param-container-inner'>
        <div class='client-readme-param-name'><code>tagFilters</code></div>
        
      </div>
    </div>
  </td>
  <td class='client-readme-param-content'>
    <p>Filter the query by a set of tags. You can AND tags by separating them with commas. To OR tags, you must add parentheses. For example, <code>tags=tag1,(tag2,tag3)</code> means <em>tag1 AND (tag2 OR tag3)</em>. You can also use a string array encoding. For example, <code>tagFilters: [&quot;tag1&quot;,[&quot;tag2&quot;,&quot;tag3&quot;]]</code> means <em>tag1 AND (tag2 OR tag3)</em>.</p>

At indexing, tags should be added in the _tags attribute of objects. For example {"_tags":["tag1","tag2"]}.

  </td>
</tr>
<tr>
  <td valign='top'>
    <div class='client-readme-param-container'>
      <div class='client-readme-param-container-inner'>
        <div class='client-readme-param-name'><code>facetFilters</code></div>
        
      </div>
    </div>
  </td>
  <td class='client-readme-param-content'>
    <p>Filter the query with a list of facets. Facets are separated by commas and is encoded as <code>attributeName:value</code>. To OR facets, you must add parentheses. For example: <code>facetFilters=(category:Book,category:Movie),author:John%20Doe</code>. You can also use a string array encoding. For example, <code>[[&quot;category:Book&quot;,&quot;category:Movie&quot;],&quot;author:John%20Doe&quot;]</code>.</p>

  </td>
</tr>



<tr>
  <td valign='top'>
    <div class='client-readme-param-container'>
      <div class='client-readme-param-container-inner'>
        <div class='client-readme-param-name'><code>facets</code></div>
        
      </div>
    </div>
  </td>
  <td class='client-readme-param-content'>
    <p>List of object attributes that you want to use for faceting. For each of the declared attributes, you&#39;ll be able to retrieve a list of the most relevant facet values, and their associated count for the current query.</p>

Attributes are separated by a comma. For example, "category,author". You can also use JSON string array encoding. For example, ["category","author"]. Only the attributes that have been added in attributesForFaceting index setting can be used in this parameter. You can also use * to perform faceting on all attributes specified in attributesForFaceting. If the number of results is important, the count can be approximate, the attribute exhaustiveFacetsCount in the response is true when the count is exact.

  </td>
</tr>



<tr>
  <td valign='top'>
    <div class='client-readme-param-container'>
      <div class='client-readme-param-container-inner'>
        <div class='client-readme-param-name'><code>maxValuesPerFacet</code></div>
        
      </div>
    </div>
  </td>
  <td class='client-readme-param-content'>
    <p>Limit the number of facet values returned for each facet. For example, <code>maxValuesPerFacet=10</code> will retrieve a maximum of 10 values per facet.</p>

  </td>
</tr>
<tr>
  <td valign='top'>
    <div class='client-readme-param-container'>
      <div class='client-readme-param-container-inner'>
        <div class='client-readme-param-name'><code>filters</code></div>
        
      </div>
    </div>
  </td>
  <td class='client-readme-param-content'>
    <p>Filter the query with numeric, facet or/and tag filters. The syntax is a SQL like syntax, you can use the OR and AND keywords. The syntax for the underlying numeric, facet and tag filters is the same than in the other filters:

available=1 AND (category:Book OR NOT category:Ebook) AND public date: 1441745506 TO 1441755506 AND inStock > 0 AND author:"John Doe"

The list of keywords is:

  • OR: create a disjunctive filter between two filters.
  • AND: create a conjunctive filter between two filters.
  • TO: used to specify a range for a numeric filter.
  • NOT: used to negate a filter. The syntax with the - isn’t allowed.
  </td>
</tr>
*Note*: To specify a value with spaces or with a value equal to a keyword, it's possible to add quotes.

Warning:

  • Like for the other filters (for performance reasons), it's not possible to have FILTER1 OR (FILTER2 AND FILTER3).
  • It's not possible to mix different categories of filters inside an OR like: num=3 OR tag1 OR facet:value
  • It's not possible to negate a group, it's only possible to negate a filter: NOT(FILTER1 OR (FILTER2) is not allowed.
<tr>
  <td valign='top'>
    <div class='client-readme-param-container'>
      <div class='client-readme-param-container-inner'>
        <div class='client-readme-param-name'><code>distinct</code></div>
        
      </div>
    </div>
  </td>
  <td class='client-readme-param-content'>
    <p>If set to 1, enables the distinct feature, disabled by default, if the <code>attributeForDistinct</code> index setting is set. This feature is similar to the SQL &quot;distinct&quot; keyword. When enabled in a query with the <code>distinct=1</code> parameter, all hits containing a duplicate value for the attributeForDistinct attribute are removed from results. For example, if the chosen attribute is <code>show_name</code> and several hits have the same value for <code>show_name</code>, then only the best one is kept and the others are removed.</p>

  </td>
</tr>

To get a full understanding of how Distinct works, you can have a look at our guide on distinct.

Multiple queries

You can send multiple queries with a single API call using a batch of queries:

var client = algoliasearch('ApplicationID', 'apiKey');
 
var queries = [{
  indexName: 'categories',
  query: 'search in categories index',
  params: {
    hitsPerPage: 3
  }
}, {
  indexName: 'products',
  query: 'first search in products',
  params: {
    hitsPerPage: 3,
    tagFilters: 'promotion'
  }
}, {
  indexName: 'products',
  query: 'another search in products',
  params: {
    hitsPerPage: 10
  }
}];
 
function searchCallback(errcontent) {
  if (err) {
    console.error(err);
    return;
  }
 
  var categories = content.results[0];
  for (var i = 0; i < categories.hits.length; ++i) {
    console.log(categories.hits[i]);
  }
 
  var products_promotion = content.results[1];
  for (var i = 0; i < products_promotion.hits.length; ++i) {
    console.log(products_promotion.hits[i]);
  }
 
  var products = content.results[2];
  for (var i = 0; i < products.hits.length; ++i) {
    console.log(products.hits[i]);
  }
}
 
// perform 3 queries in a single API call: 
//  - 1st query targets index `categories` 
//  - 2nd and 3rd queries target index `products` 
client.search(queries, searchCallback);

The resulting JSON answer contains a results array storing the underlying queries answers. The answers order is the same than the requests order.

You can specify a strategy parameter to optimize your multiple queries:

  • none: Execute the sequence of queries until the end.
  • stopIfEnoughMatches: Execute the sequence of queries until the number of hits is reached by the sum of hits.

Get an object

You can easily retrieve an object using its objectID and optionally specify a comma separated list of attributes you want:

// Retrieves all attributes 
index.getObject('myID', function(errcontent) {
  console.log(content.objectID + "" + content.toString());
});
 
// Retrieves firstname and lastname attributes 
index.getObject('myID', ['firstname', 'lastname'], function(errcontent) {
  console.log(content.objectID + "" + content.toString());
});

You can also retrieve a set of objects:

index.getObjects(['myObj1', 'myObj2'], function(errcontent) {
  console.log(content);
});

Delete an object

You can delete an object using its objectID:

index.deleteObject('myID', function(error) {
  if (!err) {
    console.log('success');
  }
});

Delete by query

You can delete all objects matching a single query with the following code. Internally, the API client performs the query, deletes all matching hits, and waits until the deletions have been applied.

// no query parameters 
index.deleteByQuery('John', function(error) {
  if (!err) {
    console.log('success');
  }
});
 
// with query parameters 
index.deleteByQuery('John', {
  some: 'query',
  param: 'eters'
}, function(error) {
  if (!err) {
    console.log('success');
  }
});

Index Settings

You can easily retrieve or update settings:

index.getSettings(function(errcontent) {
  console.log(content);
});
index.setSettings({'customRanking': ['desc(followers)']}, function(err) {
  if (!err) {
    console.log('success');
  }
});
<tr>
  <td valign='top'>
    <div class='client-readme-param-container'>
      <div class='client-readme-param-container-inner'>
        <div class='client-readme-param-name'><code>attributesToIndex</code></div>
        <div class="client-readme-param-meta"><div><em>Type: <strong>array of strings</strong></em></div></div>
      </div>
    </div>
  </td>
  <td class='client-readme-param-content'>
    <p>The list of attributes you want index (i.e. to make searchable).</p>

If set to null, all textual and numerical attributes of your objects are indexed. Make sure you updated this setting to get optimal results.

This parameter has two important uses:

  • Limit the attributes to index.
    For example, if you store the URL of a picture, you want to store it and be able to retrieve it, but you probably don't want to search in the URL.
  • Control part of the ranking.
    Matches in attributes at the beginning of the list will be considered more important than matches in attributes further down the list. In one attribute, matching text at the beginning of the attribute will be considered more important than text after. You can disable this behavior if you add your attribute inside unordered(AttributeName). For example, attributesToIndex: ["title", "unordered(text)"]. You can decide to have the same priority for two attributes by passing them in the same string using a comma as a separator. For example title and alternative_title have the same priority in this example, which is different than text priority: attributesToIndex:["title,alternative_title", "text"]. To get a full description of how the Ranking works, you can have a look at our Ranking guide.
  • numericAttributesToIndex: (array of strings) All numerical attributes are automatically indexed as numerical filters (allowing filtering operations like < and <=). If you don't need filtering on some of your numerical attributes, you can specify this list to speed up the indexing.
    If you only need to filter on a numeric value with the operator '=', you can speed up the indexing by specifying the attribute with equalOnly(AttributeName). The other operators will be disabled.
  </td>
</tr>



<tr>
  <td valign='top'>
    <div class='client-readme-param-container'>
      <div class='client-readme-param-container-inner'>
        <div class='client-readme-param-name'><code>attributesForFaceting</code></div>
        <div class="client-readme-param-meta"><div><em>Type: <strong>array of strings</strong></em></div></div>
      </div>
    </div>
  </td>
  <td class='client-readme-param-content'>
    <p>The list of fields you want to use for faceting. All strings in the attribute selected for faceting are extracted and added as a facet. If set to null, no attribute is used for faceting.</p>

  </td>
</tr>



<tr>
  <td valign='top'>
    <div class='client-readme-param-container'>
      <div class='client-readme-param-container-inner'>
        <div class='client-readme-param-name'><code>attributeForDistinct</code></div>
        <div class="client-readme-param-meta"><div><em>Type: <strong>string</strong></em></div></div>
      </div>
    </div>
  </td>
  <td class='client-readme-param-content'>
    <p>The name of the attribute used for the <code>Distinct</code> feature. This feature is similar to the SQL &quot;distinct&quot; keyword. When enabled in queries with the <code>distinct=1</code> parameter, all hits containing a duplicate value for this attribute are removed from the results. For example, if the chosen attribute is <code>show_name</code> and several hits have the same value for <code>show_name</code>, then only the first one is kept and the others are removed from the results. To get a full understanding of how <code>Distinct</code> works, you can have a look at our <a href="https://www.algolia.com/doc/search/distinct">guide on distinct</a>.</p>

  </td>
</tr>



<tr>
  <td valign='top'>
    <div class='client-readme-param-container'>
      <div class='client-readme-param-container-inner'>
        <div class='client-readme-param-name'><code>ranking</code></div>
        <div class="client-readme-param-meta"><div><em>Type: <strong>array of strings</strong></em></div></div>
      </div>
    </div>
  </td>
  <td class='client-readme-param-content'>
    <p>Controls the way results are sorted.</p>

We have nine available criteria:

  • typo: Sort according to number of typos.
  • geo: Sort according to decreasing distance when performing a geo location based search.
  • words: Sort according to the number of query words matched by decreasing order. This parameter is useful when you use the optionalWords query parameter to have results with the most matched words first.
  • proximity: Sort according to the proximity of the query words in hits.
  • attribute: Sort according to the order of attributes defined by attributesToIndex.
  • exact:
    • If the user query contains one word: sort objects having an attribute that is exactly the query word before others. For example, if you search for the TV show "V", you want to find it with the "V" query and avoid getting all popular TV shows starting by the letter V before it.
    • If the user query contains multiple words: sort according to the number of words that matched exactly (not as a prefix).
  • custom: Sort according to a user defined formula set in the customRanking attribute.
  • asc(attributeName): Sort according to a numeric attribute using ascending order. attributeName can be the name of any numeric attribute in your records (integer, double or boolean).
  • desc(attributeName): Sort according to a numeric attribute using descending order. attributeName can be the name of any numeric attribute in your records (integer, double or boolean).
    The standard order is ["typo", "geo", "words", "proximity", "attribute", "exact", "custom"]. To get a full description of how the Ranking works, you can have a look at our Ranking guide.
  </td>
</tr>



<tr>
  <td valign='top'>
    <div class='client-readme-param-container'>
      <div class='client-readme-param-container-inner'>
        <div class='client-readme-param-name'><code>customRanking</code></div>
        <div class="client-readme-param-meta"><div><em>Type: <strong>array of strings</strong></em></div></div>
      </div>
    </div>
  </td>
  <td class='client-readme-param-content'>
    <p>Lets you specify part of the ranking.</p>

The syntax of this condition is an array of strings containing attributes prefixed by the asc (ascending order) or desc (descending order) operator. For example, "customRanking" => ["desc(population)", "asc(name)"].

To get a full description of how the Custom Ranking works, you can have a look at our Ranking guide.

  </td>
</tr>



<tr>
  <td valign='top'>
    <div class='client-readme-param-container'>
      <div class='client-readme-param-container-inner'>
        <div class='client-readme-param-name'><code>queryType</code></div>
        <div class="client-readme-param-meta"><div><em>Default: <strong>prefixLast</strong></em></div></div>
      </div>
    </div>
  </td>
  <td class='client-readme-param-content'>
    <p>Select how the query words are interpreted. It can be one of the following values:</p>
  • prefixAll: All query words are interpreted as prefixes.
  • prefixLast: Only the last word is interpreted as a prefix (default behavior).
  • prefixNone: No query word is interpreted as a prefix. This option is not recommended.
  </td>
</tr>



<tr>
  <td valign='top'>
    <div class='client-readme-param-container'>
      <div class='client-readme-param-container-inner'>
        <div class='client-readme-param-name'><code>separatorsToIndex</code></div>
        <div class="client-readme-param-meta"><div><em>Default: <strong>empty</strong></em></div></div>
      </div>
    </div>
  </td>
  <td class='client-readme-param-content'>
    <p>Specify the separators (punctuation characters) to index. By default, separators are not indexed. Use <code>+#</code> to be able to search Google+ or C#.</p>

  </td>
</tr>