API reference > Search

Search REST API

Last updated 12 October 2017

Introduction

Important

We’ve developed API clients for the most common programming languages and platforms. These clients are advanced wrappers on top of our REST API itself and have been made in order to help you integrating the service within your apps: for both indexing and search. Everything that can be done using the REST API can be done using those clients.

Using our API clients is recommended to get the best from our service, they are all open-source and available on Github. You should only use our REST API to develop new API clients.

Click on one of the links below to access the client or integration’s code and documentation

Server side API Clients

PHP

Ruby

JavaScript

Python

Java

Scala

Client side API Clients

JavaScript

iOS

Android

Frameworks

Rails

Symfony

Django

Laravel

Note: SLA on both Indexing and Search are guaranteed only if you use those Official API clients. Learn more

Quick Reference

The REST API lets your interact directly with Algolia from anything that can send an HTTP request. All API access must use HTTPS.

The primary hosts are {Application-ID}.algolia.net for write operations and {Application-ID}-dsn.algolia.net for read operations. The *-dsn host guarantees high availability through automatic load balancing and also leverages our Distributed Search Network (if you subscribed that option).

In order to guarantee a very high availability, we recommend to implement a retry strategy for all API calls on the following fallback hosts: {Application-ID}-1.algolianet.com, {Application-ID}-2.algolianet.com, {Application-ID}-3.algolianet.com. (Note that the domain is different because it is hosted on another DNS provider, for better redundancy.) It is best to shuffle (randomize) the list of fallback hosts at init time in order to ensure load balancing across clients. All our standard API clients implement this retry strategy.

The Application-ID variable can be found in your dashboard.

The relative path prefix /1/ indicates that we are currently using version 1 of the API.

Indices API

Path	Verb	Method
/1/indexes/`{indexName}`/query	POST	Search an index
/1/indexes/`{indexName}`	GET	Search an index (alternative)
/1/indexes/*/queries	POST	Search multiple indexes
/1/indexes/`{indexName}`/facets/`{facetName}`/query	POST	Search for facet values
/1/indexes/`{indexName}`	POST	Add an object without ID
/1/indexes/`{indexName}`/`{objectID}`	PUT	Add/update an object by ID
/1/indexes/`{indexName}`/`{objectID}`	DELETE	Delete an object
/1/indexes/`{indexName}`/deleteByQuery	POST	Delete by query
/1/indexes/`{indexName}`/`{objectID}`/partial	POST	Partially update an object
/1/indexes/*/objects	POST	Retrieve multiple objects
/1/indexes/`{indexName}`/`{objectID}`	GET	Retrieve an object
/1/indexes/`{indexName}`/settings	GET	Get index settings
/1/indexes/`{indexName}`/settings	PUT	Change index settings
/1/indexes/`{indexName}`/keys	POST	Add an index-specific API key
/1/indexes/`{indexName}`/keys/`{key}`	PUT	Update an index-specific API key
/1/indexes/`{indexName}`/keys	GET	List index-specific API keys
/1/indexes/*/keys	GET	List index-specific API keys (for all indices)
/1/indexes/`{indexName}`/keys/`{key}`	GET	Retrieve an index-specific API key
/1/indexes/`{indexName}`/keys/`{key}`	DELETE	Delete an index-specific API key
/1/indexes/`{indexName}`/clear	POST	Clear index
/1/indexes/`{indexName}`	DELETE	Delete index
/1/indexes/`{indexName}`/operation	POST	Copy/move an index
/1/indexes	GET	List indexes
/1/indexes/`{indexName}`/batch	POST	Batch write operations
/1/indexes/*/batch	POST	Batch write operations (multiple indices)
/1/indexes/`{indexName}`/browse	POST	Browse all index content
/1/indexes/`{indexName}`/browse	GET	Browse all index content (alternative)
/1/indexes/`{indexName}`/task/`{taskID}`	GET	Get a task's status

Synonyms API

Path	Verb	Method
/1/indexes/`{indexName}`/synonyms/`{objectID}`	PUT	Create/update a synonym
/1/indexes/`{indexName}`/synonyms/batch	POST	Batch synonyms
/1/indexes/`{indexName}`/synonyms/`{objectID}`	GET	Get a synonym
/1/indexes/`{indexName}`/synonyms/clear	POST	Delete all synonyms
/1/indexes/`{indexName}`/synonyms/`{objectID}`	DELETE	Delete one synonyms set
/1/indexes/`{indexName}`/synonyms/search	POST	Search synonyms

Keys API

Path	Verb	Method
/1/keys	POST	Add an API key
/1/keys/`{key}`	PUT	Update an API key
/1/keys	GET	List API keys
/1/keys/`{key}`	GET	Get a API key
/1/keys/`{key}`	DELETE	Delete an API Key

Logs API

Path	Verb	Method
/1/logs	GET	Get latest logs

Format

The entire API uses JSON encoded as UTF-8.

The body of POST and PUT requests must be either a JSON object or a JSON array (depending on the particular endpoint) and their Content-Type header should be set to application/json; charset=UTF-8.

The body of responses is always a JSON object, and their content type is always application/json; charset=UTF-8.

Parameters

Unless otherwise stated, parameters must be passed:

in the URL’s query string for GET and DELETE requests;
in the request’s body for PUT and POST requests.

Parameters passed in the URL must be properly URL-encoded, using the UTF-8 encoding for non-ASCII characters. Furthermore, the plus character (+) is interpreted as a space (it is therefore an alternative to %20).

Arrays

Unless otherwise stated, arrays passed in the URL can be specified either:

as a comma-separated string; example: attributesToRetrieve=title,description; or
as a JSON array (which must be properly URL-encoded, of course); example: attributesToRetrieve=%5B%22title%22,%22description%22%5D.

Arrays passed in the body must always be regular JSON arrays.

Authentication

Basics

Authentication is done via HTTP headers:

X-Algolia-Application-Id identifies which application you are accessing;
X-Algolia-API-Key authenticates the endpoint (you can pass any API key created with the API).

For JavaScript usage, Algolia supports Cross-Origin Resource Sharing (CORS), so that you can use these headers in conjunction with XMLHttpRequest.

Secured API keys

You may have a single index containing per-user data. In that case, you may wish to restrict access to the records of one particular user. Typically, all your records would be tagged with their associated user_id, and you would add a filter at query time like filters=user_id:${requested_id} to retrieve only what the querying user has access to.

Adding that filter directly from the frontend (browser or mobile application) will result in a security breach, because the user would be able to modify the filters you’ve set, e.g. by modifying the JavaScript code.

In order to keep sending the query from the browser (which is recommended for optimal latency) but only target secured records, you can generate secured API keys from your backend and use them in your frontend code. The backend will then automatically enforce the security filters contained in the key; the user will not be able to alter them.

A secured API key is used like any other API key via the X-Algolia-API-Key request header.

Generate a secured API key

Secured API keys are generated by hashing (HMAC SHA-256) the following criteria together:

a private API key (can be any API Key that is not the admin API Key), used as the secret for HMAC SHA-256;
a URL-encoded list of query parameters defining the security filters.

The result of the hashing is concatenated to the URL-encoded query parameters, and this content is encoded in Base64 to generate the final secured API key.

All our backend API clients contain helpers to generate secured API keys. It is highly recommended that you use them instead of generating secured API keys manually.

Restriction parameters

The query parameters used during the generation of a secured API key can contain any of the default query parameters. In addition to these parameters, you can also specify parameters to restrict the indices or the TTL:

Name	Type	Description
userToken	string	An identifier that will be used by the rate-limit system to differentiate users behind the same IP.
validUntil	integer	Unix timestamp used to define the expiration date of the API key.
restrictIndices	comma-separated string list	List of index names allowed for the secured API key
referers	string array	Restrict this new API key to specific referers. If empty or blank, defaults to all referers. You can specify a pattern with either a leading or trailing wildcard (``), or both.\n\nFor example, `https://algolia.com/` matches all referers starting with `https://algolia.com/` and `.algolia.com` matches all referers ending with `.algolia.com`. You can combine both, as in `algolia.com*` to allow the domain `algolia.com`.
restrictSources	string	IPv4 network allowed for the secured API key

Error handling

Whether a request succeeded is indicated by the HTTP status code. A 2xx status code indicates success, whereas a 4xx status code indicates failure.

When a request fails, the response body is still JSON, but always contains a message field with a description of the error, which you can inspect for debugging. For example, trying to add an object with an invalid key will return the message:

type	URL-encoded string
mandatory	no
default	`""` (no search parameters)
description	Search parameters

Path	/1/indexes/`{indexName}`/facets/`{facetName}`/query
HTTP Verb	POST

type	URL-encoded query string
mandatory	no
default	`""`
description	Search parameters. You may use this parameter to specify parameters specific to this endpoint. You may also specify any number of other regular search parameters. They will apply to objects in the index.

Error Code	Reason
400	Attribute `facetName` is not in `attributesForFaceting`, or not with the `searchable()` specifier
404	Index `indexName` does not exist

type	boolean
mandatory	no
default	`true`
description	When true, a partial update on a nonexistent object will create the object, assuming an empty object as the basis. When false, a partial update on a nonexistent object will be ignored.

type	array of strings
mandatory	no
default	all retrievable attributes
formerly known as	`attributes`
description	List of attributes to retrieve. If not specified, all retrievable attributes are returned. `objectID` is always retrieved, even when not specified. Attributes listed in unretrievableAttributes will not be retrieved even if requested, unless the request is authenticated with the admin API key.

attributesToRetrieve `settings` `search`	List of object attributes you want to retrieve.
restrictSearchableAttributes `search`	List of attributes to be considered for textual search.

filters `search`	Filter the query with numeric, facet and/or tag filters.
facets `search`	Facets to retrieve.
maxValuesPerFacet `settings` `search`	Maximum number of facet values returned for each facet.
facetFilters `search`	Filter hits by facet value.
facetingAfterDistinct `search`	Force faceting to be applied after de-duplication.
optionalFilters `search`	Create filters for ranking purposes, to rank higher records that contain the filter(s)
sumOrFiltersScores `search`	Determines how to calculate the total score for filtering

attributesToHighlight `settings` `search`	List of attributes to highlight.
attributesToSnippet `settings` `search`	List of attributes to snippet, with an optional maximum number of words to snippet.
highlightPreTag `settings` `search`	String inserted before highlighted parts in highlight and snippet results.
highlightPostTag `settings` `search`	String inserted after highlighted parts in highlight and snippet results.
snippetEllipsisText `settings` `search`	String used as an ellipsis indicator when a snippet is truncated.
restrictHighlightAndSnippetArrays `settings` `search`	Restrict arrays in highlight and snippet results to items that matched the query.

page `search`	Number of the page to retrieve.
hitsPerPage `settings` `search`	Maximum number of hits per page.
offset `search`	Offset of the first hit to return (zero-based).
length `search`	Maximum number of hits to return. (1000 is the maximum)

type	string
mandatory	no
default	`"none"`
description	Allows optimizing execution of the queries by potentially skipping some of them. The following values are allowed: `none`: Execute all queries. `stopIfEnoughMatches`: Execute queries one by one, but stop as soon as one query matches at least as many hits as its `hitsPerPage` parameter. More formally: query N is executed only if all of queries 0 through N-1 had strictly less hits than their requested number of hits per page. Let’s illustrate `stopIfEnoughMatches`: Let’s say you send 3 queries with `hitsPerPage` set to 50, 5 and 20 (respectively). There are different possible scenarios: Run query #1 50+ hits are found: skip to step 4 otherwise: continue with query #2 Run query #2 5+ hits where found: skip to step 4 otherwise: continue with query #3 Run query #3 This is the last query, so we don’t care about its outcome Return results Return actual results for queries that were processed Return empty hits for queries that were skipped, along with a `processed` attribute set to `false`

minWordSizefor1Typo `settings` `search`	Minimum number of characters a word in the query string must contain to accept matches with one typo.
minWordSizefor2Typos `settings` `search`	Minimum number of characters a word in the query string must contain to accept matches with two typos.
typoTolerance `settings` `search`	Controls whether typo tolerance is enabled and how it is applied:
allowTyposOnNumericTokens `settings` `search`	Whether to allow typos on numbers ("numeric tokens") in the query string.
ignorePlurals `settings` `search`	Consider singular and plurals forms a match without typo.
disableTypoToleranceOnAttributes `settings` `search`	List of attributes on which you want to disable typo tolerance

aroundLatLng `search`	Search for entries around a given location.
aroundLatLngViaIP `search`	Search for entries around a given location automatically computed from the requester's IP address.
aroundRadius `search`	Maximum radius for geo search (in meters).
aroundPrecision `search`	Precision of geo search (in meters).
minimumAroundRadius `search`	Minimum radius (in meters) used for a geo search when <%= parameter_link('aroundRadius') -%> is not set.
insideBoundingBox `search`	Search inside a rectangular area (in geo coordinates).
insidePolygon `search`	Search inside a polygon (in geo coordinates).

queryType `search` `settings`	Controls if and how query words are interpreted as prefixes.
removeWordsIfNoResults `settings` `search`	Selects a strategy to remove words from the query when it doesn't match any hits.
advancedSyntax `settings` `search`	Enables the advanced query syntax.
optionalWords `settings` `search`	List of words that should be considered as optional when found in the query.
removeStopWords `settings` `search`	Remove stop words from the query before executing it.
disableExactOnAttributes `settings` `search`	List of attributes on which you want to disable computation of the `exact` ranking criterion
exactOnSingleWordQuery `settings` `search`	Controls how the `exact` ranking criterion is computed when the query contains only one word.
alternativesAsExact `setting` `search`	List of alternatives that should be considered an exact match by the `exact` ranking criterion.

enableRules `search` `settings`	Whether rules should be globally enabled.
ruleContexts `search`	Enables contextual rules.

minProximity `settings` `search`	Precision of the `proximity` ranking criterion.
responseFields `settings` `search`	Choose which fields the response will contain. Applies to search and browse queries.
maxFacetHits `settings` `search`	Maximum number of facet hits to return during a search for facet values.
percentileComputation `search`	Whether to include the query in processing time percentile computation.
distinct `settings` `search`	Controls de-duplication of results.
getRankingInfo `search`	Enables detailed ranking information.
numericFilters `search`	Filter hits based on values of numeric attributes.
tagFilters `search`	Filter hits by tags.
analytics `search`	Whether the current query will be taken into account in the Analytics.
analyticsTags `search`	List of tags to apply to the query in the Analytics.
synonyms `search`	Whether to take into account synonyms defined for the targeted index.
replaceSynonymsInHighlight `settings` `search`	Whether to replace words matched via synonym expansion by the matched synonym in highlight and snippet results.

searchableAttributes `settings`	List of attributes eligible for textual search.
attributesForFaceting `settings`	List of attributes you want to use for faceting.
unretrievableAttributes `settings`	List of attributes that cannot be retrieved at query time.
attributesToRetrieve `settings` `search`	List of object attributes you want to retrieve.

ranking `settings`	Controls the way results are sorted.
customRanking `settings`	Specifies the `custom` ranking criterion.
replicas `settings`	List of indices to which you want to replicate all write operations.

hitsPerPage `settings` `search`	Maximum number of hits per page.
paginationLimitedTo `settings`	Maximum number of hits accessible via pagination.

numericAttributesForFiltering `settings`	List of numeric attributes that can be used as numerical filters.
allowCompressionOfIntegerArray `settings`	Enables compression of large integer arrays.

attributeForDistinct `settings`	Name of the de-duplication attribute for the <%= parameter_link('distinct') -%> feature.
minProximity `settings` `search`	Precision of the `proximity` ranking criterion.
responseFields `settings` `search`	Choose which fields the response will contain. Applies to search and browse queries.
maxFacetHits `settings` `search`	Maximum number of facet hits to return during a search for facet values.
camelCaseAttributes `settings`	List of attributes on which to do a decomposition of camel case words.
distinct `settings` `search`	Controls de-duplication of results.
replaceSynonymsInHighlight `settings` `search`	Whether to replace words matched via synonym expansion by the matched synonym in highlight and snippet results.

Search REST API

Introduction

Important

Server side API Clients

Client side API Clients

Frameworks

Quick Reference

Indices API

Synonyms API

Keys API

Logs API

Format

Parameters

Arrays

Authentication

Basics

Secured API keys

Generate a secured API key

Restriction parameters

Error handling

Indices API

Search an index

Description

Parameters

params

Example

Errors

Search an index (alternative)

Description

Parameters

Example

Errors

Search multiple indexes

Description

Parameters

requests

strategy

Example

Errors

Search for facet values

Description

Parameters

params

facetQuery

maxFacetHits

Example

Errors

Add an object without ID

Description

Example

Errors

Add/update an object by ID

Description

Example

Errors

Delete an object

Description

Example

Delete by query

Description

Example

Partially update an object

Description

Parameters

createIfNotExists

Example

Errors

Retrieve multiple objects

Description

Example

Errors

Retrieve an object

Description

Parameters

attributesToRetrieve

Example

Errors

Get index settings

Description

Example