Algolia Recommend API
Returns related-products, frequently-bought-together, trending and look-alike recommendations trained from Insights events and catalog data, plus the Recommend rules that override them.
This API exposes 11 operations across 7 paths, and defines 168 schemas. It is described by OpenAPI 3.2.0, at version 1.0.0.
Requests are made against 5 base URLs: https://{appId}.algolia.net, https://{appId}-1.algolianet.com, https://{appId}-2.algolianet.com, https://{appId}-3.algolianet.com, https://{appId}-dsn.algolia.net.
11 operations
7 paths
168 schemas
2 DELETE4 GET4 POST1 PUT
Metadata
The identity and technical contract details declared by the specification.
Authentication & Security 2
Algolia Recommend API declares
2 security schemes
for authenticating requests.
An API key is passed in the header as x-algolia-application-id (appId).
An API key is passed in the header as x-algolia-api-key (apiKey).
By default, every request must be authenticated.
appId— Your Algolia application ID.apiKey— Your Algolia API key with the necessary permissions to make the request. Permissions are controlled through access control lists (ACL) and access restrictions.…
Paths & Operations 11
Across 7 paths, the API surfaces 11 operations — 2 DELETE, 4 GET, 4 POST, 1 PUT. Each is listed below with its method, path, parameters, and response codes.
recommend 11
GET
/{path}
Send requests to the Algolia REST API
POST
/{path}
Send requests to the Algolia REST API
PUT
/{path}
Send requests to the Algolia REST API
DELETE
/{path}
Send requests to the Algolia REST API
POST
/1/indexes/*/recommendations
Retrieve recommendations
GET
/1/indexes/{indexName}/{model}/recommend/rules/{objectID}
Retrieve a rule
DELETE
/1/indexes/{indexName}/{model}/recommend/rules/{objectID}
Delete a rule
GET
/1/indexes/{indexName}/{model}/task/{taskID}
Check task status
POST
/1/indexes/{indexName}/{model}/recommend/rules/search
Search for rules
POST
/1/indexes/{indexName}/{model}/recommend/rules/batch
Create or update a batch of Recommend Rules
GET
/setClientApiKey
Switch the API key used to authenticate requests
Schemas 168
The contract defines 168 schemas that model the data the API accepts and returns. The most detailed are baseRecommendIndexSettings (36 properties), baseRecommendSearchParams (26 properties), baseSearchResponse (26 properties), baseIndexSettings (20 properties). Each schema is shown below with its type and property counts.
filters
string
Filter expression to only include items that match the filter criteria in the response. You can use these filter expressions: - Numeric filters. , where is one…
facetOrdering
object
Order of facet names and facet values in your UI.
2 properties
HideConsequenceObject
object
Object ID of the recommendation you want to exclude.
1 property
aroundLatLngViaIP
boolean
Whether to obtain the coordinates from the request's IP address.
lookingSimilarModel
string
Looking similar model. This model recommends items that look similar to the item with the ID objectID based on image attributes in your index.
relatedProducts
object
3 properties
2 required
widgets
object
Widgets returned from any rules that are applied to the current search.
1 property
maxValuesPerFacet
integer
Maximum number of facet values to return for each facet.
rankingInfo
object
Object with detailed information about the record's ranking.
13 properties
5 required
reRankingApplyFilter
Restrict [Dynamic Re-Ranking](https://www.algolia.com/doc/guides/algolia-ai/re-ranking) to records that match these filters.
searchParamsQuery
object
1 property
analytics
boolean
Whether this search will be included in Analytics.
IndexSettings_advancedSyntaxFeatures
array
Advanced search syntax features you want to support - exactPhrase. Phrases in quotes must match exactly. For example, sparkly blue "iPhone case" only returns r…
highlightedValue
string
Highlighted attribute value, including HTML tags.
trendingFacetsQuery
optionalFilters
Filters to promote or demote records in the search results. Optional filters work like facet filters, but they don't exclude records from the search results. R…
AutoFacetFilter
object
Facet attribute. Only recommendations with the same value (or only recommendations with a different value) as the original viewed item are included.
2 properties
aroundRadius
Maximum radius for a search around a central location. This parameter works in combination with the aroundLatLng and aroundLatLngViaIP parameters. By default,…
parameters_page
integer
Requested page of the API response. Algolia uses page and hitsPerPage to control how search results are displayed ([paginated](https://www.algolia.com/doc/guid…
ignorePlurals
Treat singular, plurals, and other forms of declensions as equivalent. Only use this feature for the languages used in your index.
baseRecommendIndexSettings
object
36 properties
replaceSynonymsInHighlight
boolean
Whether to replace a highlighted word with the matched synonym By default, the original words are highlighted even if a synonym matches. For example, with home…
restrictHighlightAndSnippetArrays
boolean
Whether to restrict highlighting and snippeting to items that at least partially matched the search query. By default, all items are highlighted and snippeted.
trendingItemsQuery
minimumAroundRadius
integer
Minimum radius (in meters) for a search around a location when aroundRadius isn't set.
disableTypoToleranceOnAttributes
array
Attributes for which you want to turn off [typo tolerance](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/typo-tolerance). Attribu…
synonyms
boolean
Whether to take into account an index's synonyms for this search.
snippetResultMap
object
Snippets that show the context around a matching search query.
aroundPrecisionFromValue
array
facetFilters
Filter the search by facet values, so that only records with the same facet values are retrieved. Prefer using the filters parameter, which supports all filter…
facetValue
string
Facet value. To be used in combination with facetName. If specified, only recommendations matching the facet filter will be returned.
recommendSearchParams
Search parameters for filtering the recommendations.
insideBoundingBoxArray
array
Coordinates for a rectangular area in which to search. Each bounding box is defined by the two opposite points of its diagonal, and expressed as latitude and l…
removeStopWords
Removes stop words from the search query. Stop words are common words like articles, conjunctions, prepositions, or pronouns that have little or no meaning on…
boughtTogetherQuery
snippetResult
highlightResultArray
array
Surround words that match the query with HTML tags for highlighting.
baseIndexSettings
object
20 properties
recommendScore
number
Recommendation score.
taskID
integer
Unique identifier of a task. A successful API response means that a task was added to a queue. It might not run immediately. You can check the task's progress…
percentileComputation
boolean
Whether to include this search when calculating processing-time percentiles.
snippetResultArray
array
Snippets that show the context around a matching search query.
relevancyStrictness
integer
Relevancy threshold below which less relevant results aren't included in the results You can only set relevancyStrictness on [virtual replica indices](https://…
facetName
string
Facet attribute. To be used in combination with facetValue. If specified, only recommendations matching the facet filter will be returned.
baseSearchResponse
object
26 properties
page
integer
Page of search results to retrieve.
ErrorBase
object
Error.
1 property
processingTimeMS
integer
Time the server took to process the request, in milliseconds.
minProximity
integer
Minimum proximity score for two matching words This adjusts the [Proximity ranking criterion](https://www.algolia.com/doc/guides/managing-results/relevance-ove…
allowTyposOnNumericTokens
boolean
Whether to allow typos on numbers in the search query Turn off this setting to reduce the number of irrelevant matches when searching in large sets of similar…
sortRemainingBy
string
Order of facet values that aren't explicitly positioned with the order setting. - count. Order remaining facet values by decreasing count. The count is the num…
bannerImageUrl
object
URL for an image to show inside a banner.
1 property
SearchPagination
object
4 properties
parameters_query
string
Search query.
disableExactOnAttributes
array
Searchable attributes for which you want to [turn off the Exact ranking criterion](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/…
advancedSyntaxFeatures
string
renderingContent
object
Extra data that can be used in the search UI. You can use this to control aspects of your search UI, such as the order of facet names and values without changi…
3 properties
context
string
An additional restriction that only triggers the rule, when the search has the same value as ruleContexts parameter. For example, if context: mobile, the rule…
snippetResultOption
object
Snippets that show the context around a matching search query.
2 properties
2 required
recommendationsRequest
recommendIndexSettings
Index settings.
PromoteConsequence
array
Place items at specific positions in the list of recommendations.
personalizationImpact
integer
Impact that Personalization should have on this search The higher this value is, the more Personalization determines the ranking compared to other factors. For…
matchLevel
string
Whether the whole query string matches or only a part.
taskStatus
string
Task status, published if the task is completed, notPublished otherwise.
updatedAt
string
Date and time when the object was updated, in RFC 3339 format.
relatedQuery
deletedAt
string
Date and time when the object was deleted, in RFC 3339 format.
facetingAfterDistinct
boolean
Whether faceting should be applied after deduplication with distinct This leads to accurate facet counts when using faceting in combination with distinct. It's…
facets
array
Facets for which to retrieve facet values that match the search criteria and the number of matching facet values To retrieve all facets, use the wildcard chara…
responseFields
array
Properties to include in the API response of search and browse requests By default, all response properties are included. To reduce the response size, you can…
naturalLanguages
array
ISO language codes that adjust settings that are useful for processing natural language queries (as opposed to keyword searches) - Sets removeStopWords and ign…
supportedLanguage
string
ISO code for a supported language.
fbtModel
string
Frequently bought together model. This model recommends items that have been purchased within 1 day with the item with the ID objectID.
baseRecommendRequest
object
4 properties
2 required
matchedGeoLocation
object
3 properties
lookingSimilar
object
3 properties
2 required
parameters_hitsPerPage
integer
Maximum number of hits per page. Algolia uses page and hitsPerPage to control how search results are displayed ([paginated](https://www.algolia.com/doc/guides/…
distinct
Determines how many records of a group are included in the search results. Records with the same value for the attributeForDistinct attribute are considered a…
fallbackParams
Search parameters to use for a fallback request if there aren't enough recommendations.
order
array
Explicit order of facets or facet values. This setting lets you always show specific facets or facet values at the top of the list.
redirectURL
object
The redirect rule container.
1 property
ParamsConsequence
object
Filter or boost recommendations matching a facet filter.
3 properties
analyticsTags
array
Tags to apply to the query for [segmenting analytics data](https://www.algolia.com/doc/guides/search-analytics/guides/segments).
highlightResultMap
object
Surround words that match the query with HTML tags for highlighting.
booleanString
string
bannerImage
object
Image to show inside a banner.
2 properties
IndexSettings_facets
object
Order of facet names.
1 property
banner
object
Banner with image and link to redirect users.
2 properties
nbPages
integer
Number of pages of results.
Condition
object
Condition that triggers the rule. If not specified, the rule is triggered for all recommendations.
2 properties
aroundRadiusAll
string
Return all records with a valid geoloc attribute. Don't filter by distance.
aroundPrecision
Precision of a coordinate-based search in meters to group results with similar distances. The Geo ranking criterion considers all matches within the same range…
recommendHit
object
Recommend hit.
6 properties
1 required
PromoteConsequenceObject
object
Object ID and position of the recommendation you want to pin.
2 properties
minWordSizefor1Typo
integer
Minimum number of characters a word in the search query must contain to accept matches with [one typo](https://www.algolia.com/doc/guides/managing-results/opti…
IndexSettings_alternativesAsExact
array
Determine which plurals and synonyms should be considered an exact matches By default, Algolia treats singular and plural forms of a word, and single-word syno…
recommendationsHits
object
1 property
1 required
highlightResultOption
object
Surround words that match the query with HTML tags for highlighting.
4 properties
3 required
snippetEllipsisText
string
String used as an ellipsis indicator when a snippet is truncated.
trendingItemsModel
string
Trending items model. Trending items are determined from the number of conversion events collected on them.
recommendationsHit
frequentlyBoughtTogether
object
3 properties
2 required
ruleContexts
array
Assigns a rule context to the search query [Rule contexts](https://www.algolia.com/doc/guides/managing-results/rules/rules-overview/how-to/customize-search-res…
trendingFacetHit
object
Trending facet hit.
3 properties
2 required
RedirectRuleIndexMetadata
object
5 properties
5 required
values
object
Order of facet values. One object for each facet.
ruleID
string
Unique identifier of a rule object.
maxFacetHits
integer
Maximum number of facet values to return when [searching for facet values](https://www.algolia.com/doc/guides/managing-results/refine-results/faceting/search-f…
baseRecommendSearchParams
object
26 properties
aroundLatLng
string
Coordinates for the center of a circle, expressed as a comma-separated string of latitude and longitude. Only records included within a circle around this cent…
alternativesAsExact
string
personalization
object
3 properties
bannerLink
object
Link for a banner defined in the Merchandising Studio.
1 property
clickAnalytics
boolean
Whether to include a queryID attribute in the response The query ID is a unique identifier for a search query and is required for tracking [click and conversio…
queryLanguages
array
Languages for language-specific query processing steps such as plurals, stop-word removal, and word-detection dictionaries. This setting sets a default list of…
HideConsequence
array
Exclude items from recommendations.
indexName
string
Index name (case-sensitive).
numericFilters
Filter by numeric facets. Prefer using the filters parameter, which supports all filter types and combinations with boolean operators. You can use numeric comp…
attributesToHighlight
array
Attributes to highlight By default, all searchable attributes are highlighted. Use to highlight all attributes or use an empty array [] to turn off highlightin…
minWordSizefor2Typos
integer
Minimum number of characters a word in the search query must contain to accept matches with [two typos](https://www.algolia.com/doc/guides/managing-results/opt…
trendingFacetsModel
string
Trending facet values model. This model recommends trending facet values for the specified facet attribute.
advancedSyntax
boolean
Whether to support phrase matching and excluding words from search queries Use the advancedSyntaxFeatures parameter to control which feature is supported.
decompoundQuery
boolean
Whether to split compound words in the query into their building blocks For more information, see [Word segmentation](https://www.algolia.com/doc/guides/managi…
distinctSeqID
integer
relatedModel
string
Related products or similar content model. This model recommends items that are similar to the item with the ID objectID. Similarity is determined from the use…
enableRules
boolean
Whether to enable rules.
timeRange
object
2 properties
tagFilters
Filter the search by values of the special tags attribute. Prefer using the filters parameter, which supports all filter types and combinations with boolean op…
optionalWords
Words that should be considered optional when found in the query. By default, records must match all words in the search query to be included in the search res…
sumOrFiltersScores
boolean
Whether to sum all filter scores If true, all filter scores are summed. Otherwise, the maximum filter score is kept. For more information, see [filter scores](…
userData
An object with custom data. You can store up to 32kB as custom data.
restrictSearchableAttributes
array
Restricts a search to a subset of your searchable attributes. Attribute names are case-sensitive.
highlightPostTag
string
HTML tag to insert after the highlighted parts in all highlighted results and snippets.
objectID
string
Unique record identifier.
removeWordsIfNoResults
string
Strategy for removing words from the query when it doesn't return any results. This helps to avoid returning empty search results. - none. No words are removed…
nbHits
integer
Number of results (hits).
recommendModels
string
typoTolerance
Whether [typo tolerance](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/typo-tolerance) is enabled and how it is applied. If typo…
userToken
string
Unique pseudonymous or anonymous user identifier. This helps with analytics and click and conversion events. For more information, see [user token](https://www…
queryType
string
Determines if and how query words are interpreted as prefixes. By default, only the last query word is treated as a prefix (prefixLast). To turn off prefix sea…
recommendUpdatedAtResponse
object
Response, taskID, and update timestamp.
2 properties
2 required
enableReRanking
boolean
Whether this search will use [Dynamic Re-Ranking](https://www.algolia.com/doc/guides/algolia-ai/re-ranking) This setting only has an effect if you activated Dy…
hitsPerPage
integer
Number of hits per page.
insidePolygon
array
Coordinates of a polygon in which to search. Polygons are defined by 3 to 10,000 points. Each point is represented by its latitude and longitude. Provide multi…
RecommendRule
object
Recommend rule.
7 properties
trendingFacets
object
5 properties
4 required
exactOnSingleWordQuery
string
Determines how the [Exact ranking criterion](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/override-search-engine-defaults/in-dep…
attributesToRetrieve
array
Attributes to include in the API response To reduce the size of your response, you can retrieve only some of the attributes. Attribute names are case-sensitive…
enablePersonalization
boolean
Whether to enable Personalization.
sortFacetValuesBy
string
Order in which to retrieve facet values - count. Facet values are retrieved by decreasing count. The count is the number of matching records containing this fa…
insideBoundingBox
highlightPreTag
string
HTML tag to insert before the highlighted parts in all highlighted results and snippets.
typoToleranceEnum
string
- min. Return matches with the lowest number of typos. For example, if you have matches without typos, only include those. But if there are no matches without…
value
object
3 properties
getRankingInfo
boolean
Whether the search response should include detailed ranking information.
recommendationsResults
attributesToSnippet
array
Attributes for which to enable snippets. Attribute names are case-sensitive Snippets provide additional context to matched words. If you enable snippets, they…
similarQuery
string
Keywords to be used instead of the search query to conduct a more broader search Using the similarQuery parameter changes other settings - queryType is set to…
banners
array
Banners defined in the Merchandising Studio for a given search.
hide
array
Hide facet values.
lookingSimilarQuery
optionalWordsArray
array
List of [optional words](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/empty-or-insufficient-results/creating-a-list-of-optional-…
attributeCriteriaComputedByMinProximity
boolean
Whether the best matching attribute should be determined by minimum proximity This setting only affects ranking if the Attribute ranking criterion comes before…
query
string
Search query.
highlightResult
trendingItems
object
4 properties
1 required
Consequence
object
Effect of the rule.
3 properties
Specification
The full machine-readable OpenAPI contract behind this narrative.
Source
#Recommendations#REST
Where this information came from
This is an independent, third-party profile of Algolia Recommend API, published by API Evangelist. We do not operate, host, resell, or support these APIs, and we are not affiliated with or endorsed by the company unless stated above. Everything here is built from publicly available information — the company's own site, developer portal, documentation, public repositories, and the specifications it publishes for public use. Nothing is obtained by breaching a system, defeating an access control, or using credentials.
The Kin Score and Agent Readiness rating are independently calculated assessments of a company's public API artifacts, scored against a published rubric. They are not certifications, endorsements, security assessments, or audits.
Corrections, re-scores, and removal are free — no partnership or purchase required, and you do not need to justify the request. A removed company is recorded as unrated, never scored zero for having asked. Acknowledgement within one business day; removal within two.
info@apievangelist.com
·
Read the full data-sourcing policy →
On a security or compliance team? Put security in the subject line and
you will get a person, not a form — we will tell you exactly which public URLs this profile was built from.