Search REST API

The text to search for in the index.

If empty or absent, the textual search will match any object.

List of object attributes you want to retrieve.

This can be used to minimize the size of the response.

You can use * to retrieve all values.

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.

List of attributes to be considered for textual search.

It must be a subset of the searchableAttributes index setting.

restrictSearchableAttributes is a search time parameter, it will only affect the current query. It will not override your index settings.

searchableAttributes must not be empty nor null for restrictSearchableAttributes to be applied.

Filter the query with numeric, facet and/or tag filters.

This parameter uses a SQL-like expression syntax, where you can use boolean operators and parentheses to combine individual filters.

The following individual filters are supported:

• Numeric filter:

  • Comparison: ${attributeName} ${operator} ${operand} matches all objects where the specified numeric attribute satisfies the numeric condition expressed by the operator and the operand. The operand must be a numeric value. Supported operators are <, <=, =, !=, >= and >, with the same semantics as in virtually all programming languages. Example: inStock > 0.

  • Range: ${attributeName}:${lowerBound} TO ${upperBound} matches all objects where the specified numeric attribute is within the range [${lowerBound}, ${upperBound}] (inclusive on both ends). Example: publication_date: 1441745506 TO 1441755506.

• Facet filter: ${facetName}:${facetValue} matches all objects containing exactly the specified value in the specified facet attribute. Facet matching is case sensitive. Example: category:Book.

• Tag filter: _tags:${value} (or, alternatively, just ${value}) matches all objects containing exactly the specified value in their _tags attribute. Tag matching is case sensitive. Example: _tags:published.

Individual filters can be combined via boolean operators. The following operators are supported:

• OR: must match any of the combined conditions (disjunction)
• AND: must match all of the combined conditions (conjunction)
• NOT: negate a filter

Finally, parentheses, ( and ), can be used for grouping.

Putting it all together, an example is:

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

Keywords are case-sensitive.

If no attribute name is specified, the filter applies to _tags. For example: public OR user_42 will translate into _tags:public OR _tags:user_42.

If a value contains spaces, or conflicts with a keyword, you can use double quotes.

If a filtered attribute contains an array of values, any matching value will cause the filter to match.

For performance reasons, filter expressions are limited to a disjunction of conjunctions. In other words, you can have ANDs of ORs (e.g. filter1 AND (filter2 OR filter3)), but not ORs of ANDs (e.g. filter1 OR (filter2 AND filter3).

You cannot mix different filter categories inside a disjunction (OR). For example, num=3 OR tag1 OR facet:value is not allowed.

You cannot negate a group of filters, only an individual filter. For example, NOT(filter1 OR filter2) is not allowed.

Facets to retrieve.

If not specified or empty, no facets are retrieved. The special value * may be used to retrieve all facets.

Facets must have been declared beforehand in the attributesForFaceting index setting.

For each of the retrieved facets, the response will contain a list of the most frequent facet values in objects matching the current query. Each value will be returned with its associated count (number of matched objects containing that value).

Faceting does not filter your results. If you want to filter results, you should use filters.

If the number of hits is high, facet counts may be approximate. The response field exhaustiveFacetsCount is true when the count is exact.

Maximum number of facet values returned for each facet.

The API enforces a hard limit of 1000 on maxValuesPerFacet. Any value above that limit will be interpreted as 1000.

Filter hits by facet value.

The filters parameter provides an easier to use, SQL-like syntax. We recommend using it instead of facetFilters.

Each string represents a filter on a given facet value. It must follow the syntax ${attributeName}:${value}.

If you specify multiple filters, they are interpreted as a conjunction (AND). If you want to use a disjunction (OR), use a nested array.

Examples:

• ["category:Book", "author:John Doe"] translates as category:Book AND author:"John Doe"
• [["category:Book", "category:Movie"], "author:John Doe"] translates as (category:Book OR category:Movie) AND author:"John Doe"

Negation is supported by prefixing the value with a minus sign (-, a.k.a. dash). For example: ["category:Book", "category:-Movie"] translates as category:Book AND NOT category:Movie.

Force faceting to be applied after de-duplication.

When using the distinct setting in combination with faceting, facet counts may be higher than expected. This is because the engine computes faceting before applying de-duplication (distinct).

When facetingAfterDistinct is set to true, you force faceting to be computed after de-duplication has been applied.

Please take precautions, though, and carefully read the limitations:

• You should not use facetingAfterDistinct=true if you don’t have the same facet values in all records sharing the same distinct key (you would get inconsistent results).
• facetingAfterDistinct can only be set at query time; it can’t be added as a default setting of the index.
• facetingAfterDistinct will be ignored if you also set typoTolerance to either strict or min.

List of attributes to highlight.

If set to null, all searchable attributes are highlighted (see searchableAttributes). The special value * may be used to highlight all attributes.

Only string values can be highlighted. Numerics will be ignored.

When highlighting is enabled, each hit in the response will contain an additional _highlightResult object (provided that at least one of its attributes is highlighted) with the following fields:

• value (string): Markup text with occurrences highlighted. The tags used for highlighting are specified via highlightPreTag and highlightPostTag.

• matchLevel (string, enum) = {none | partial | full}: Indicates how well the attribute matched the search query.

• matchedWords (array): List of words from the query that matched the object.

• fullyHighlighted (boolean): Whether the entire attribute value is highlighted.

List of attributes to snippet, with an optional maximum number of words to snippet.

If set to null, no attributes are snippeted. The special value * may be used to snippet all attributes.

The syntax for each attribute is ${attributeName}:${nbWords}. The number of words can be omitted, and defaults to 10.

Only string values can be snippeted. Numerics will be ignored.

When snippeting is enabled, each hit in the response will contain an additional _snippetResult object (provided that at least one of its attributes is snippeted) with the following fields:

• value (string): Markup text with occurrences highlighted and optional ellipsis indicators. The tags used for highlighting are specified via highlightPreTag and highlightPostTag. The text used to indicate ellipsis is specified via snippetEllipsisText.

• matchLevel (string, enum) = {none | partial | full}: Indicates how well the attribute matched the search query.

String inserted before highlighted parts in highlight and snippet results.

highlightPreTag usually need to be use along with highlightPostTag.

String inserted after highlighted parts in highlight and snippet results.

highlightPostTag usually needs to be used along with highlightPreTag.

String used as an ellipsis indicator when a snippet is truncated.

Defaults to an empty string for all accounts created before February 10th, 2016. Defaults to … (U+2026, HORIZONTAL ELLIPSIS) for accounts created after that date.

Restrict arrays in highlight and snippet results to items that matched the query.

When false, all array items are highlighted/snippeted. When true, only array items that matched at least partially are highlighted/snippeted.

Number of the page to retrieve.

The number of page depends on the value of hitsPerPage. If hitsPerPage=20, the page=2 will display the hits from 41 to 60.

Page numbers are zero-based. Therefore, in order to retrieve the 10th page, you need to set page=9.

Maximum number of hits per page.

Offset of the first hit to return (zero-based).

In most cases, page/hitsPerPage is the recommended method for pagination.

Maximum number of hits to return. (1000 is the maximum)

In most cases, page/hitsPerPage is the recommended method for pagination.

Minimum number of characters a word in the query string must contain to accept matches with one typo.

Minimum number of characters a word in the query string must contain to accept matches with two typos.

Controls whether typo tolerance is enabled and how it is applied:

• true: Typo tolerance is enabled and all matching hits are retrieved (default behavior).

• false: Typo tolerance is entirely disabled. Hits matching with only typos are not retrieved.

• min: Only keep results with the minimum number of typos. For example, if just one hit matches without typos, then all hits with only typos are not retrieved.

• strict: Hits matching with 2 typos or more are not retrieved if there are some hits matching without typos. This option is useful to avoid “false positives” as much as possible.

Whether to allow typos on numbers (“numeric tokens”) in the query string.

When false, typo tolerance is disabled on numeric tokens. For example, the query 304 will match 30450 but not 40450 (which would have been the case with typo tolerance enabled).

This option can be very useful on serial numbers and zip codes searches.

Consider singular and plurals forms a match without typo.

For example, “car” and “cars”, or “foot” and “feet” will be considered equivalent.

This parameter may be:

• a boolean: enable or disable plurals for all supported languages;
• a list of language ISO codes for which plurals should be enabled.

This option is set to false by default.

For optimum relevance, it is highly recommended that you enable only languages that are used in your data. Enabling all languages may cause side effects, with pairs of words being unexpectedly treated as equivalent.

List of supported languages with their associated ISO code:

Afrikaans=af, Arabic=ar, Azeri=az, Bulgarian=bg, Catalan=ca, Czech=cs, Welsh=cy, Danis=da, German=de, English=en, Esperanto=eo, Spanish=es, Estonian=et, Basque=eu, Finnish=fi, Faroese=fo, French=fr, Galician=gl, Hebrew=he, Hindi=hi, Hungarian=hu, Armenian=hy, Indonesian=id, Icelandic=is, Italian=it, Japanese=ja, Georgian=ka, Kazakh=kk, Korean=ko, Kyrgyz=ky, Lithuanian=lt, Maori=mi, Mongolian=mn, Marathi=mr, Malay=ms, Maltese=mt, Norwegian=nb, Dutch=nl, Northern Sotho=ns, Polish=pl, Pashto=ps, Portuguese=pt, Quechua=qu, Romanian=ro, Russian=ru, Slovak=sk, Albanian=sq, Swedish=sv, Swahili=sw, Tamil=ta, Telugu=te, Tagalog=tl, Tswana=tn, Turkish=tr, Tatar=tt

List of attributes on which you want to disable typo tolerance

The list must be a subset of the searchableAttributes index setting.

searchableAttributes must not be empty nor null for disableTypoToleranceOnAttributes to be applied.

Search for entries around a given location.

You can specified this as two floats separated by a comma.

Search for entries around a given location automatically computed from the requester’s IP address.

If you are sending the request from your servers, you must set the X-Forwarded-For HTTP header with the client’s IP address for it to be used as the basis for the computation of the search location.

Maximum radius for geo search (in meters).

If set, only hits within the specified radius (in meters) from the searched location will be returned.

If not set, the radius is automatically computed from the density of the searched area. You can retrieve the computed radius in the automaticRadius response field. You may specify a minimum value for the automatic radius via minimumAroundRadius.

The special value all causes the geo distance to be computed and taken into account for ranking, but without filtering; this option is faster than specifying a high integer value.

Precision of geo search (in meters).

When ranking hits, geo distances are grouped into ranges of aroundPrecision size. All hits within the same range are considered equal with respect to the geo ranking parameter.

For example, if you set aroundPrecision to 100, any two objects lying in the range [0, 99m] from the searched location will be considered equal; same for [100, 199], [200, 299], etc.

Minimum radius (in meters) used for a geo search when aroundRadius is not set.

This parameter is ignored when aroundRadius is set.

Search inside a rectangular area (in geo coordinates).

The rectangle is defined by two diagonally opposite points (hereafter p1 and p2), hence by 4 floats: p1Lat, p1Lng, p2Lat, p2Lng.

For example: insideBoundingBox=47.3165,4.9665,47.3424,5.0201

You may specify multiple bounding boxes, in which case the search will use the union (OR) of the rectangles. To specify multiple rectangles, pass either:

• more than 4 values (must be a multiple of 4: 8, 12…); example: 47.3165,4.9665,47.3424,5.0201,40.9234,2.1185,38.6430,1.9916; or
• an array of arrays of floats (each inner array must contain exactly 4 values); example: [[47.3165, 4.9665, 47.3424, 5.0201], [40.9234, 2.1185, 38.6430, 1.9916]].

Search inside a polygon (in geo coordinates).

The polygon is defined by a set of points (minimum 3), each defined by its latitude and longitude. You therefore need an even number of floats, with a minimum of 6: p1Lat, p1Lng, p2Lat, p2Lng, p3Lat, p3Long.

For example: insidePolygon=47.3165,4.9665,47.3424,5.0201,47.32,4.98

You may specify multiple polygons, in which case the search will use the union (OR) of the polygons. To specify multiple polygons, pass an array of arrays of floats (each inner array must contain an even number of values, with a minimum of 6); example: [[47.3165, 4.9665, 47.3424, 5.0201, 47.32, 4.9], [40.9234, 2.1185, 38.6430, 1.9916, 39.2587, 2.0104]].

Controls if and how query words are interpreted as prefixes.

It may be one of the following values:

• prefixLast: Only the last word is interpreted as a prefix (default behavior).

• prefixAll: All query words are interpreted as prefixes. This option is not recommended, as it tends to yield counterintuitive results and has a negative impact on performance.

• prefixNone: No query word is interpreted as a prefix. This option is not recommended, especially in an instant search setup, as the user will have to type the entire word(s) before getting any relevant results.

Selects a strategy to remove words from the query when it doesn’t match any hits.

The goal is to avoid empty results by progressively loosening the query until hits are matched.

There are four different options:

• none: No specific processing is done when a query does not return any results (default behavior).

• lastWords: When a query does not return any results, treat the last word as optional. The process is repeated with words N-1, N-2, etc. until there are results, or the beginning of the query string has been reached.

• firstWords: When a query does not return any results, treat the first word as optional. The process is repeated with words 2, 3, etc. until there are results, or the end of the query string has been reached.

• allOptional: When a query does not return any results, make a second attempt treating all words as optional. This is equivalent to transforming the implicit AND operator applied between query words to an OR.

Enables the advanced query syntax.

This advanced syntax brings two additional features:

• Phrase query: a specific sequence of terms that must be matched next to one another. A phrase query needs to be surrounded by double quotes ("). For example, "search engine" will only match records having search next to engine.

  Typo tolerance is disabled inside the phrase (i.e. within the quotes).

• Prohibit operator: excludes records that contain a specific term. This term has to be prefixed by a minus (-, a.k.a dash). For example, search -engine will only match records containing search but not engine.

List of words that should be considered as optional when found in the query.

You don’t need to put commas between words. Each string will automatically be tokenized into words, all of which will be considered as optional.

Remove stop words from the query before executing it.

This parameter may be:

• a boolean: enable or disable stop words for all supported languages; or
• a list of language ISO codes for which stop word removal should be enabled.

In most use-cases, we don’t recommend enabling stop word removal.

Stop word removal is useful when you have a query in natural language, e.g. “what is a record?”. In that case, the engine will remove “what”, “is” and “a” before executing the query, and therefore just search for “record”. This will remove false positives caused by stop words, especially when combined with optional words (see optionalWords and removeWordsIfNoResults). For most use cases, however, it is better not to use this feature, as people tend to search by keywords on search engines (i.e. they naturally omit stop words).

Stop words removal is only applied on query words that are not interpreted as prefixes.

As a consequence, the behavior of removeStopWords also depends on the queryType parameter:

• queryType=prefixLast means the last query word is a prefix and won’t be considered for stop word removal;
• queryType=prefixNone means no query word is a prefix, therefore stop word removal will be applied to all query words;
• queryType=prefixAll means all query words are prefixes, therefore no stop words will be removed.

List of supported languages with their associated ISO code:

Arabic=ar, Armenian=hy, Basque=eu, Bengali=bn, Brazilian=pt-br, Bulgarian=bg, Catalan=ca, Chinese=zh, Czech=cs, Danish=da, Dutch=nl, English=en, Finnish=fi, French=fr, Galician=gl, German=de, Greek=el, Hindi=hi, Hungarian=hu, Indonesian=id, Irish=ga, Italian=it, Japanese=ja, Korean=ko, Kurdish=ku, Latvian=lv, Lithuanian=lt, Marathi=mr, Norwegian=no, Persian (Farsi)=fa, Polish=pl, Portugese=pt, Romanian=ro, Russian=ru, Slovak=sk, Spanish=es, Swedish=sv, Thai=th, Turkish=tr, Ukranian=uk, Urdu=ur.

List of attributes on which you want to disable computation of the exact ranking criterion

The list must be a subset of the searchableAttributes index setting.

searchableAttributes must not be empty nor null for disableExactOnAttributes to be applied.

Controls how the exact ranking criterion is computed when the query contains only one word.

The following values are allowed:

• attribute (default): the exact ranking criterion is set to 1 if the query string exactly matches an entire attribute value. For example, if you search for the TV show “V”, you want it to match the query “V” before all popular TV shows starting with the letter V.
• none: the exact ranking criterion is ignored on single word queries;
• word: the exact ranking criterion is set to 1 if the query word is found in the record. The query word must be at least 3 characters long and must not be a stop word in any supported language.

List of alternatives that should be considered an exact match by the exact ranking criterion.

The following values are allowed:

• ignorePlurals: alternative words added by the ignorePlurals feature;
• singleWordSynonym: single-word synonyms (example: “NY” = “NYC”);
• multiWordsSynonym: multiple-words synonyms (example: “NY” = “New York”).

Controls de-duplication of results.

A non-zero value enables de-duplication; a zero value disables it. Booleans are also accepted (though not recommended): false is treated as 0, and true is treated as 1.

De-duplication requires a de-duplication attribute to be configured via the attributeForDistinct index setting. If not configured, distinct will be accepted at query time but silently ignored.

This feature is similar to the SQL distinct keyword. When set to N (where N > 0), at most N hits will be returned with the same value for the de-duplication attribute.

Example: If the de-duplication attribute is show_name and distinct is set to 1, then if several hits have the same value for show_name, only the most relevant one is kept (with respect to the ranking formula); the others are removed.

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

Enables detailed ranking information.

When true, each hit in the response contains an additional _rankingInfo object containing the following fields:

• nbTypos (integer): Number of typos encountered when matching the record. Corresponds to the typos ranking criterion in the ranking formula.

• firstMatchedWord (integer): Position of the most important matched attribute in the attributes to index list. Corresponds to the attribute ranking criterion in the ranking formula.

• proximityDistance (integer): When the query contains more than one word, the sum of the distances between matched words. Corresponds to the proximity criterion in the ranking formula.

• userScore (integer): Custom ranking for the object, expressed as a single numerical value. Conceptually, it’s what the position of the object would be in the list of all objects sorted by custom ranking. Corresponds to the custom criterion in the ranking formula.

• geoDistance (integer): Distance between the geo location in the search query and the best matching geo location in the record, divided by the geo precision.

• geoPrecision (integer): Precision used when computed the geo distance, in meters. All distances will be floored to a multiple of this precision.

• nbExactWords (integer): Number of exactly matched words. If alternativeAsExact is set, it may include plurals and/or synonyms.

• words (integer): Number of matched words, including prefixes and typos.

• filters (integer): This field is reserved for advanced usage. It will be zero in most cases.

In addition, the response contains the following additional top-level fields:

• serverUsed (string): Actual host name of the server that processed the request. (Our DNS supports automatic failover and load balancing, so this may differ from the host name used in the request.)

• parsedQuery (string): The query string that will be searched, after normalization. Normalization includes removing stop words (if removeStopWords is enabled), and transforming portions of the query string into phrase queries (see advancedSyntax).

• timeoutCounts (boolean): Whether a timeout was hit when computing the facet counts. When true, the counts will be interpolated (i.e. approximate). See also exhaustiveFacetsCount.

• timeoutHits (boolean): Whether a timeout was hit when retrieving the hits. When true, some results may be missing.

Filter hits based on values of numeric attributes.

The filters parameter provides an easier to use, SQL-like syntax. We recommend using it instead of numericFilters.

Each string represents a filter on a numeric attribute. Two forms are supported:

• Comparison: ${attributeName} ${operator} ${operand} matches all objects where the specified numeric attribute satisfies the numeric condition expressed by the operator and the operand. The operand must be a numeric value. Supported operators are <, <=, =, !=, >= and >, with the same semantics as in virtually all programming languages. Example: inStock > 0.

• Range: ${attributeName}:${lowerBound} TO ${upperBound} matches all objects where the specified numeric attribute is within the range [${lowerBound}, ${upperBound}] (inclusive on both ends). Example: price: 0 TO 1000.

If you specify multiple filters, they are interpreted as a conjunction (AND). If you want to use a disjunction (OR), use a nested array.

Filter hits by tags.

Tags must be contained in a top-level _tags attribute of your objects at indexing time.

Tags are essentially an implicit facet on the _tags attribute. We therefore recommend that you use facets instead. See attributesForFaceting and facets.

The filters parameter provides an easier to use, SQL-like syntax. We recommend using it instead of tagFilters.

Each string represents a given tag value that must be matched.

If you specify multiple tags, they are interpreted as a conjunction (AND). If you want to use a disjunction (OR), use a nested array.

Whether the current query will be taken into account in the Analytics.

List of tags to apply to the query in the Analytics.

Tags can be used in the Analytics to filter searches.

Whether to take into account synonyms defined for the targeted index.

Whether to replace words matched via synonym expansion by the matched synonym in highlight and snippet results.

When true, highlighting and snippeting will use words from the query rather than the original words from the objects. When false, highlighting and snippeting will always display the original words from the objects.

Multiple words can be replaced by a one-word synonym, but not the other way round. For example, if “NYC” and “New York City” are synonyms, searching for “NYC” will replace “New York City” with “NYC” in highlights and snippets, but searching for “New York City” will not replace “NYC” with “New York City” in highlights and snippets.

Precision of the proximity ranking criterion.

By default, the minimum (and best) proximity value between two matching words is 1.

Setting it to 2 (respectively N) would allow 1 (respectively N-1) additional word(s) to be found between two matching words without degrading the proximity ranking value.

Example: considering the query “javascript framework”, if you set minProximity to 2, two records containing respectively “JavaScript framework” and “JavaScript charting framework” will get the same proximity score, even if the latter contains an additional word between the two matching words.

The maximum value for minProximity is 7. Any higher value will disable the proximity criterion in the ranking formula.

Choose which fields the response will contain. Applies to search and browse queries.

By default, all fields are returned. If this parameter is specified, only the fields explicitly listed will be returned, unless * is used, in which case all fields are returned. Specifying an empty list or unknown field names is an error.

This parameter is mainly intended to limit the response size. For example, in complex queries, echoing of request parameters in the response’s params field can be undesirable.

List of fields that can be filtered out:

• aroundLatLng
• automaticRadius
• exhaustiveFacetsCount
• facets
• facets_stats
• hits
• hitsPerPage
• index
• length
• nbHits
• nbPages
• offset
• page
• params
• processingTimeMS
• query
• queryAfterRemoval

List of fields that cannot be filtered out:

• message
• warning
• cursor
• serverUsed
• timeoutCounts (deprecated, please use exhaustiveFacetsCount instead)
• timeoutHits (deprecated, please use exhaustiveFacetsCount instead)
• parsedQuery
• all fields triggered by getRankingInfo

Maximum number of facet hits to return during a search for facet values.

Does not apply to regular search queries.

For performance reasons, the maximum allowed number of returned values is 100. Any value outside the range [1, 100] will be rejected.

Whether to include the query in processing time percentile computation.

When true, the API records the processing time of the search query and includes it when computing the 90% and 99% percentiles, available in your Algolia dashboard.

When false, the search query is excluded from percentile computation.

List of attributes eligible for textual search.

In search engine parlance, those attributes will be “indexed”, i.e. their content will be made searchable.

If not specified or empty, all string values of all attributes are indexed. If specified, only the specified attributes are indexed; any numerical values within those attributes are converted to strings and indexed.

When an attribute is listed, it is recursively processed, i.e. all of its nested attributes, at any depth, are indexed according to the same policy.

Make sure you adjust this setting to get optimal results.

This parameter has two important uses:

1. Limit the scope of the search. Restricting the searchable attributes to those containing meaningful text guarantees a better relevance. For example, if your objects have associated pictures, you need to store the picture URLs in the records in order to retrieve them for display at query time, but you probably don’t want to search inside the URLs.

   A side effect of limiting the attributes is increased performance: it keeps the index size at a minimum, which has a direct and positive impact on both build time and search speed.

2. Control part of the ranking. The contents of the searchableAttributes parameter impacts ranking in two complementary ways:

   • Attribute priority: The order in which attributes are listed defines their ranking priority: matches in attributes at the beginning of the list will be considered more important than matches in attributes further down the list.

     To assign the same priority to several attributes, pass them within the same string, separated by commas. For example, by specifying ["title,alternative_title", "text"], title and alternative_title will have the same priority, but a higher priority than text.

   • Importance of word positions: Within a given attribute, matches near the beginning of the text are considered more important than matches near the end. You can disable this behavior by wrapping your attribute name inside an unordered() modifier. For example, ["title", "unordered(text)"] will consider all positions inside the text attribute as equal, but positions inside the title attribute will still matter.

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

List of attributes you want to use for faceting.

All strings within these attributes will be extracted and added as facets. If not specified or empty, no attribute will be faceted.

If you want to search for values of a given facet (using the Search for facet values method) you need to specify searchable(attributeName).

If you only need to filter on a given facet, you can specify filterOnly(attributeName). It reduces the size of the index and the build time.

List of attributes that cannot be retrieved at query time.

These attributes can still be used for indexing and/or ranking.

This setting is bypassed when the query is authenticated with the admin API key.

List of object attributes you want to retrieve.

This can be used to minimize the size of the response.

You can use * to retrieve all values.

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.

Controls the way results are sorted.

You must specify a list of ranking criteria. They will be applied in sequence by the tie-breaking algorithm in the order they are specified.

The following ranking criteria are available:

• typo: Sort by increasing number of typos.
• geo: Sort by decreasing geo distance when performing a geo search. This criterion is ignored when not performing a geo search.
• words: Sort by decreasing number of matched query words. This parameter is useful when you use the optionalWords query parameter to rank hits with the most matched words first.
• filters: The filter criteria is the sum of scores for filters matched by one hit. In case of OR filters, only one score is taken in account even if the two filters match.
• proximity: Sort by increasing proximity of query words in hits.
• attribute: Sort according to the order of attributes defined by searchableAttributes.
• exact:
  • If the query contains only one word: The behavior depends on the value of exactOnSingleWordQuery.
  • If the query contains multiple words: Sort by decreasing number of words that matched exactly. What is considered to be an exact match depends on the value of alternativesAsExact.
• custom: Sort according to a user-defined formula specified via the customRanking setting.
• Sort by value of a numeric attribute. Here, ${attributeName} can be the name of any numeric attribute in your objects (integer, floating-point or boolean).
  • asc(${attributeName}): sort by increasing value of the attribute
  • desc(${attributeName}): sort by decreasing value of the attribute

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

Specifies the custom ranking criterion.

Each string must conform to the syntax asc(${attributeName}) or desc(${attributeName}) and specifies a (respectively) increasing or decreasing sort on an attribute. All sorts are applied in sequence by the tie-breaking algorithm in the order they are specified.

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

List of indices to which you want to replicate all write operations.

In order to get relevant results in milliseconds, we pre-compute part of the ranking during indexing. Consequently, if you want to use different ranking formulas depending on the use case, you need to create one index per ranking formula.

Multiple ranking formulas are useful to implement sort strategies (e.g. sort by price ASC, price DESC, …).

This option allows you to perform write operations on a single, primary index and automatically perform the same operations on all of its replicas.

A primary index can have as many replicas as needed. However, a replica can only have one primary; in other words, two primary indices cannot have the same replica. Furthermore, a replica cannot have its own replicas (i.e. you cannot “chain” replicas).

Maximum number of facet values returned for each facet.

The API enforces a hard limit of 1000 on maxValuesPerFacet. Any value above that limit will be interpreted as 1000.

List of attributes to highlight.

If set to null, all searchable attributes are highlighted (see searchableAttributes). The special value * may be used to highlight all attributes.

Only string values can be highlighted. Numerics will be ignored.

When highlighting is enabled, each hit in the response will contain an additional _highlightResult object (provided that at least one of its attributes is highlighted) with the following fields:

• value (string): Markup text with occurrences highlighted. The tags used for highlighting are specified via highlightPreTag and highlightPostTag.

• matchLevel (string, enum) = {none | partial | full}: Indicates how well the attribute matched the search query.

• matchedWords (array): List of words from the query that matched the object.

• fullyHighlighted (boolean): Whether the entire attribute value is highlighted.

List of attributes to snippet, with an optional maximum number of words to snippet.

If set to null, no attributes are snippeted. The special value * may be used to snippet all attributes.

The syntax for each attribute is ${attributeName}:${nbWords}. The number of words can be omitted, and defaults to 10.

Only string values can be snippeted. Numerics will be ignored.

When snippeting is enabled, each hit in the response will contain an additional _snippetResult object (provided that at least one of its attributes is snippeted) with the following fields:

• value (string): Markup text with occurrences highlighted and optional ellipsis indicators. The tags used for highlighting are specified via highlightPreTag and highlightPostTag. The text used to indicate ellipsis is specified via snippetEllipsisText.

• matchLevel (string, enum) = {none | partial | full}: Indicates how well the attribute matched the search query.

String inserted before highlighted parts in highlight and snippet results.

highlightPreTag usually need to be use along with highlightPostTag.

String inserted after highlighted parts in highlight and snippet results.

highlightPostTag usually needs to be used along with highlightPreTag.

String used as an ellipsis indicator when a snippet is truncated.

Defaults to an empty string for all accounts created before February 10th, 2016. Defaults to … (U+2026, HORIZONTAL ELLIPSIS) for accounts created after that date.

Restrict arrays in highlight and snippet results to items that matched the query.

When false, all array items are highlighted/snippeted. When true, only array items that matched at least partially are highlighted/snippeted.

Maximum number of hits per page.

Maximum number of hits accessible via pagination.

By default, this parameter is set to 1000 to guarantee good performance.

We recommend keeping the default value to guarantee excellent performance. Increasing the pagination limit will have a direct impact on the performance of search queries. A too high value will also make it very easy for anyone to retrieve (“scrape”) your entire dataset.

Minimum number of characters a word in the query string must contain to accept matches with one typo.

Minimum number of characters a word in the query string must contain to accept matches with two typos.

Controls whether typo tolerance is enabled and how it is applied:

• true: Typo tolerance is enabled and all matching hits are retrieved (default behavior).

• false: Typo tolerance is entirely disabled. Hits matching with only typos are not retrieved.

• min: Only keep results with the minimum number of typos. For example, if just one hit matches without typos, then all hits with only typos are not retrieved.

• strict: Hits matching with 2 typos or more are not retrieved if there are some hits matching without typos. This option is useful to avoid “false positives” as much as possible.

Whether to allow typos on numbers (“numeric tokens”) in the query string.

When false, typo tolerance is disabled on numeric tokens. For example, the query 304 will match 30450 but not 40450 (which would have been the case with typo tolerance enabled).

This option can be very useful on serial numbers and zip codes searches.

Consider singular and plurals forms a match without typo.

For example, “car” and “cars”, or “foot” and “feet” will be considered equivalent.

This parameter may be:

• a boolean: enable or disable plurals for all supported languages;
• a list of language ISO codes for which plurals should be enabled.

This option is set to false by default.

For optimum relevance, it is highly recommended that you enable only languages that are used in your data. Enabling all languages may cause side effects, with pairs of words being unexpectedly treated as equivalent.

List of supported languages with their associated ISO code:

Afrikaans=af, Arabic=ar, Azeri=az, Bulgarian=bg, Catalan=ca, Czech=cs, Welsh=cy, Danis=da, German=de, English=en, Esperanto=eo, Spanish=es, Estonian=et, Basque=eu, Finnish=fi, Faroese=fo, French=fr, Galician=gl, Hebrew=he, Hindi=hi, Hungarian=hu, Armenian=hy, Indonesian=id, Icelandic=is, Italian=it, Japanese=ja, Georgian=ka, Kazakh=kk, Korean=ko, Kyrgyz=ky, Lithuanian=lt, Maori=mi, Mongolian=mn, Marathi=mr, Malay=ms, Maltese=mt, Norwegian=nb, Dutch=nl, Northern Sotho=ns, Polish=pl, Pashto=ps, Portuguese=pt, Quechua=qu, Romanian=ro, Russian=ru, Slovak=sk, Albanian=sq, Swedish=sv, Swahili=sw, Tamil=ta, Telugu=te, Tagalog=tl, Tswana=tn, Turkish=tr, Tatar=tt

List of attributes on which you want to disable typo tolerance

The list must be a subset of the searchableAttributes index setting.

searchableAttributes must not be empty nor null for disableTypoToleranceOnAttributes to be applied.

List of words on which typo tolerance will be disabled.

Separators (punctuation characters) to index.

By default, separators are not indexed.

Example: Use +# to be able to search for “Google+” or “C#”.

Controls if and how query words are interpreted as prefixes.

It may be one of the following values:

• prefixLast: Only the last word is interpreted as a prefix (default behavior).

• prefixAll: All query words are interpreted as prefixes. This option is not recommended, as it tends to yield counterintuitive results and has a negative impact on performance.

• prefixNone: No query word is interpreted as a prefix. This option is not recommended, especially in an instant search setup, as the user will have to type the entire word(s) before getting any relevant results.

Selects a strategy to remove words from the query when it doesn’t match any hits.

The goal is to avoid empty results by progressively loosening the query until hits are matched.

There are four different options:

• none: No specific processing is done when a query does not return any results (default behavior).

• lastWords: When a query does not return any results, treat the last word as optional. The process is repeated with words N-1, N-2, etc. until there are results, or the beginning of the query string has been reached.

• firstWords: When a query does not return any results, treat the first word as optional. The process is repeated with words 2, 3, etc. until there are results, or the end of the query string has been reached.

• allOptional: When a query does not return any results, make a second attempt treating all words as optional. This is equivalent to transforming the implicit AND operator applied between query words to an OR.

Enables the advanced query syntax.

This advanced syntax brings two additional features:

• Phrase query: a specific sequence of terms that must be matched next to one another. A phrase query needs to be surrounded by double quotes ("). For example, "search engine" will only match records having search next to engine.

  Typo tolerance is disabled inside the phrase (i.e. within the quotes).

• Prohibit operator: excludes records that contain a specific term. This term has to be prefixed by a minus (-, a.k.a dash). For example, search -engine will only match records containing search but not engine.

List of words that should be considered as optional when found in the query.

You don’t need to put commas between words. Each string will automatically be tokenized into words, all of which will be considered as optional.

Remove stop words from the query before executing it.

This parameter may be:

• a boolean: enable or disable stop words for all supported languages; or
• a list of language ISO codes for which stop word removal should be enabled.

In most use-cases, we don’t recommend enabling stop word removal.

Stop word removal is useful when you have a query in natural language, e.g. “what is a record?”. In that case, the engine will remove “what”, “is” and “a” before executing the query, and therefore just search for “record”. This will remove false positives caused by stop words, especially when combined with optional words (see optionalWords and removeWordsIfNoResults). For most use cases, however, it is better not to use this feature, as people tend to search by keywords on search engines (i.e. they naturally omit stop words).

Stop words removal is only applied on query words that are not interpreted as prefixes.

As a consequence, the behavior of removeStopWords also depends on the queryType parameter:

• queryType=prefixLast means the last query word is a prefix and won’t be considered for stop word removal;
• queryType=prefixNone means no query word is a prefix, therefore stop word removal will be applied to all query words;
• queryType=prefixAll means all query words are prefixes, therefore no stop words will be removed.

List of supported languages with their associated ISO code:

Arabic=ar, Armenian=hy, Basque=eu, Bengali=bn, Brazilian=pt-br, Bulgarian=bg, Catalan=ca, Chinese=zh, Czech=cs, Danish=da, Dutch=nl, English=en, Finnish=fi, French=fr, Galician=gl, German=de, Greek=el, Hindi=hi, Hungarian=hu, Indonesian=id, Irish=ga, Italian=it, Japanese=ja, Korean=ko, Kurdish=ku, Latvian=lv, Lithuanian=lt, Marathi=mr, Norwegian=no, Persian (Farsi)=fa, Polish=pl, Portugese=pt, Romanian=ro, Russian=ru, Slovak=sk, Spanish=es, Swedish=sv, Thai=th, Turkish=tr, Ukranian=uk, Urdu=ur.

List of attributes on which you want to disable prefix matching

This setting is useful on attributes that contain string that should not be matched as a prefix (for example a product SKU).

The list must be a subset of the searchableAttributes index setting.

searchableAttributes must not be empty nor null for disablePrefixOnAttributes to be applied.

List of attributes on which you want to disable computation of the exact ranking criterion

The list must be a subset of the searchableAttributes index setting.

searchableAttributes must not be empty nor null for disableExactOnAttributes to be applied.

Controls how the exact ranking criterion is computed when the query contains only one word.

The following values are allowed:

• attribute (default): the exact ranking criterion is set to 1 if the query string exactly matches an entire attribute value. For example, if you search for the TV show “V”, you want it to match the query “V” before all popular TV shows starting with the letter V.
• none: the exact ranking criterion is ignored on single word queries;
• word: the exact ranking criterion is set to 1 if the query word is found in the record. The query word must be at least 3 characters long and must not be a stop word in any supported language.

List of numeric attributes that can be used as numerical filters.

If not specified, all numeric attributes are automatically indexed and available as numerical filters (via the filters parameter). If specified, only attributes explicitly listed are available as numerical filters. If empty, no numerical filters are allowed.

If you don’t need filtering on some of your numerical attributes, you can use numericAttributesForFiltering to speed up the indexing.

If you only need to filter on a numeric value based on equality (i.e. with the operators = or !=), you can speed up the indexing by specifying equalOnly(${attributeName}). Other operators will be disabled.

Enables compression of large integer arrays.

In data-intensive use-cases, we recommended enabling this feature to reach a better compression ratio on arrays exclusively containing non-negative integers (as is typical of lists of user IDs or ACLs).

When enabled, the compressed integer arrays may be reordered. Non-compressed arrays are left intact.

Name of the de-duplication attribute for the distinct feature.

Controls de-duplication of results.

A non-zero value enables de-duplication; a zero value disables it. Booleans are also accepted (though not recommended): false is treated as 0, and true is treated as 1.

De-duplication requires a de-duplication attribute to be configured via the attributeForDistinct index setting. If not configured, distinct will be accepted at query time but silently ignored.

This feature is similar to the SQL distinct keyword. When set to N (where N > 0), at most N hits will be returned with the same value for the de-duplication attribute.

Example: If the de-duplication attribute is show_name and distinct is set to 1, then if several hits have the same value for show_name, only the most relevant one is kept (with respect to the ranking formula); the others are removed.

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

Whether to replace words matched via synonym expansion by the matched synonym in highlight and snippet results.

When true, highlighting and snippeting will use words from the query rather than the original words from the objects. When false, highlighting and snippeting will always display the original words from the objects.

Multiple words can be replaced by a one-word synonym, but not the other way round. For example, if “NYC” and “New York City” are synonyms, searching for “NYC” will replace “New York City” with “NYC” in highlights and snippets, but searching for “New York City” will not replace “NYC” with “New York City” in highlights and snippets.

This is an advanced use-case to define a token substitutable by a list of words without having the original token searchable.

It is defined by a hash associating placeholders to lists of substitutable words.

The <placeholder_name> syntax is used to define placeholders in an attribute.

Precision of the proximity ranking criterion.

By default, the minimum (and best) proximity value between two matching words is 1.

Setting it to 2 (respectively N) would allow 1 (respectively N-1) additional word(s) to be found between two matching words without degrading the proximity ranking value.

Example: considering the query “javascript framework”, if you set minProximity to 2, two records containing respectively “JavaScript framework” and “JavaScript charting framework” will get the same proximity score, even if the latter contains an additional word between the two matching words.

The maximum value for minProximity is 7. Any higher value will disable the proximity criterion in the ranking formula.

Choose which fields the response will contain. Applies to search and browse queries.

By default, all fields are returned. If this parameter is specified, only the fields explicitly listed will be returned, unless * is used, in which case all fields are returned. Specifying an empty list or unknown field names is an error.

This parameter is mainly intended to limit the response size. For example, in complex queries, echoing of request parameters in the response’s params field can be undesirable.

List of fields that can be filtered out:

• aroundLatLng
• automaticRadius
• exhaustiveFacetsCount
• facets
• facets_stats
• hits
• hitsPerPage
• index
• length
• nbHits
• nbPages
• offset
• page
• params
• processingTimeMS
• query
• queryAfterRemoval

List of fields that cannot be filtered out:

• message
• warning
• cursor
• serverUsed
• timeoutCounts (deprecated, please use exhaustiveFacetsCount instead)
• timeoutHits (deprecated, please use exhaustiveFacetsCount instead)
• parsedQuery
• all fields triggered by getRankingInfo

Maximum number of facet hits to return during a search for facet values.

Does not apply to regular search queries.

For performance reasons, the maximum allowed number of returned values is 100. Any value outside the range [1, 100] will be rejected.