Recommend API (1.0.0)
Download OpenAPI specification:Download
The Recommend API lets you generate recommendations with several AI models.
Note: You should use Algolia's libraries and tools to interact with the Recommend API. Using the HTTP endpoints directly is not covered by the SLA.
Get recommendations and trending items.
Returns results from either recommendation or trending models:
- Recommendations are provided by the Related Products and Frequently Bought Together models
- Trending models are Trending Items and Trending Facet Values.
Request Body schema: application/jsonrequired
required | Array of trendingItemsQuery (object) or trendingFacetsQuery (object) or recommendationsQuery (object) or recommendedForYouQuery (object) Request parameters depend on the model (recommendations or trending). | ||||||||||||||||
Array One of
|
Responses
Request samples
- C#
- Dart
- Go
- Java
- JavaScript
- Kotlin
- PHP
- Python
- Ruby
- Scala
- Swift
// Initialize the client var client = new RecommendClient(new RecommendConfig("YOUR_APP_ID", "YOUR_API_KEY")); // Call the API var response = await client.GetRecommendationsAsync( new GetRecommendationsParams { Requests = new List<RecommendationsRequest> { new RecommendationsRequest( new RecommendationsQuery { IndexName = "indexName", ObjectID = "objectID", Model = Enum.Parse<RecommendationModels>("RelatedProducts"), Threshold = 42, } ) }, } );
Response samples
- 200
- 400
- 402
- 403
- 404
{- "results": [
- {
- "abTestID": 0,
- "abTestVariantID": 1,
- "aroundLatLng": "40.71,-74.01",
- "automaticRadius": "string",
- "exhaustive": {
- "facetsCount": true,
- "facetValues": true,
- "nbHits": true,
- "rulesMatch": true,
- "typo": true
}, - "exhaustiveFacetsCount": true,
- "exhaustiveNbHits": true,
- "exhaustiveTypo": true,
- "facets": {
- "category": {
- "food": 1,
- "tech": 42
}
}, - "facets_stats": {
- "property1": {
- "min": 0.1,
- "max": 0.1,
- "avg": 0.1,
- "sum": 0.1
}, - "property2": {
- "min": 0.1,
- "max": 0.1,
- "avg": 0.1,
- "sum": 0.1
}
}, - "hitsPerPage": 20,
- "index": "indexName",
- "indexUsed": "indexNameAlt",
- "message": "string",
- "nbHits": 20,
- "nbPages": 1,
- "nbSortedHits": 20,
- "page": 0,
- "parsedQuery": "george clo",
- "processingTimeMS": 20,
- "processingTimingsMS": { },
- "queryAfterRemoval": "string",
- "redirect": {
- "index": [
- {
- "source": "string",
- "dest": "string",
- "reason": "string",
- "succeed": true,
- "data": {
- "ruleObjectID": "string"
}
}
]
}, - "renderingContent": {
- "facetOrdering": {
- "facets": {
- "order": [
- "string"
]
}, - "values": {
- "facet1": {
- "order": [
- "string"
], - "sortRemainingBy": "alpha"
}, - "facet2": {
- "order": [
- "string"
], - "sortRemainingBy": "alpha"
}
}
}
}, - "serverTimeMS": 20,
- "serverUsed": "c2-uk-3.algolia.net",
- "userData": {
- "settingID": "f2a7b51e3503acc6a39b3784ffb84300",
- "pluginVersion": "1.6.0"
}, - "queryID": "a00dbc80a8d13c4565a442e7e2dca80a",
- "hits": [
- {
- "objectID": "string",
- "_highlightResult": {
- "attribute1": {
- "value": "<em>George</em> <em>Clo</em>oney",
- "matchLevel": "full",
- "matchedWords": [
- "action"
], - "fullyHighlighted": true
}, - "attribute2": {
- "value": "<em>George</em> <em>Clo</em>oney",
- "matchLevel": "full",
- "matchedWords": [
- "action"
], - "fullyHighlighted": true
}
}, - "_snippetResult": {
- "attribute1": {
- "value": "<em>George</em> <em>Clo</em>oney",
- "matchLevel": "full"
}, - "attribute2": {
- "value": "<em>George</em> <em>Clo</em>oney",
- "matchLevel": "full"
}
}, - "_rankingInfo": {
- "filters": 0,
- "firstMatchedWord": 0,
- "geoDistance": 0,
- "geoPrecision": 1,
- "matchedGeoLocation": {
- "lat": 0.1,
- "lng": 0.1,
- "distance": 0
}, - "personalization": {
- "filtersScore": 0,
- "rankingScore": 0,
- "score": 0
}, - "nbExactWords": 0,
- "nbTypos": 0,
- "promoted": true,
- "proximityDistance": 0,
- "userScore": 0,
- "words": 1,
- "promotedByReRanking": true
}, - "_distinctSeqID": 0,
- "_score": 100
}
], - "query": "",
- "params": "query=a&hitsPerPage=20"
}
]
}
Get a Recommend rule.
Return a Recommend rule.
path Parameters
indexName required | string Example: YourIndexName Name of the index on which to perform the operation. |
model required | string Enum: "bought-together" "related-products" "trending-facets" "trending-items" |
objectID required | string Example: 123 Unique record identifier. |
Responses
Request samples
- C#
- Dart
- Go
- Java
- JavaScript
- Kotlin
- PHP
- Python
- Ruby
- Scala
- Swift
// Initialize the client var client = new RecommendClient(new RecommendConfig("YOUR_APP_ID", "YOUR_API_KEY")); // Call the API var response = await client.GetRecommendRuleAsync( "indexName", Enum.Parse<RecommendModels>("RelatedProducts"), "objectID" );
Response samples
- 200
- 400
- 402
- 403
- 404
{- "_metadata": {
- "lastUpdate": "2023-07-04T12:49:15Z"
}, - "objectID": "hide-12345",
- "conditions": [
- {
- "pattern": "{facet:genre}",
- "anchoring": "contains",
- "alternatives": false,
- "context": "mobile",
- "filters": "genre:comedy"
}
], - "consequence": {
- "params": {
- "similarQuery": "comedy drama crime Macy Buscemi",
- "filters": "(category:Book OR category:Ebook) AND _tags:published",
- "facetFilters": [
- [
- "category:Book",
- "category:-Movie"
], - "author:John Doe"
], - "optionalFilters": [
- "category:Book",
- "author:John Doe"
], - "numericFilters": [
- [
- "inStock = 1",
- "deliveryDate < 1441755506"
], - "price < 1000"
], - "tagFilters": [
- [
- "Book",
- "Movie"
], - "SciFi"
], - "sumOrFiltersScores": false,
- "restrictSearchableAttributes": [
- "title",
- "author"
], - "facets": [
- "*"
], - "facetingAfterDistinct": false,
- "page": 0,
- "offset": 0,
- "length": 1,
- "aroundLatLng": "40.71,-74.01",
- "aroundLatLngViaIP": false,
- "aroundRadius": 1,
- "aroundPrecision": 10,
- "minimumAroundRadius": 1,
- "insideBoundingBox": [
- [
- 47.3165,
- 4.9665,
- 47.3424,
- 5.0201
], - [
- 40.9234,
- 2.1185,
- 38.643,
- 1.9916
]
], - "insidePolygon": [
- [
- 47.3165,
- 4.9665,
- 47.3424,
- 5.0201,
- 47.32,
- 4.9
], - [
- 40.9234,
- 2.1185,
- 38.643,
- 1.9916,
- 39.2587,
- 2.0104
]
], - "naturalLanguages": [ ],
- "ruleContexts": [
- "mobile"
], - "personalizationImpact": 100,
- "userToken": "test-user-123",
- "getRankingInfo": false,
- "synonyms": true,
- "clickAnalytics": false,
- "analytics": true,
- "analyticsTags": [ ],
- "percentileComputation": true,
- "enableABTest": true,
- "attributesToRetrieve": [
- "author",
- "title",
- "content"
], - "ranking": [
- "typo",
- "geo",
- "words",
- "filters",
- "proximity",
- "attribute",
- "exact",
- "custom"
], - "customRanking": [
- "desc(popularity)",
- "asc(price)"
], - "relevancyStrictness": 90,
- "attributesToHighlight": [
- "author",
- "title",
- "conten",
- "content"
], - "attributesToSnippet": [
- "content:80",
- "description"
], - "highlightPreTag": "<em>",
- "highlightPostTag": "</em>",
- "snippetEllipsisText": "…",
- "restrictHighlightAndSnippetArrays": false,
- "hitsPerPage": 20,
- "minWordSizefor1Typo": 4,
- "minWordSizefor2Typos": 8,
- "typoTolerance": true,
- "allowTyposOnNumericTokens": true,
- "disableTypoToleranceOnAttributes": [
- "sku"
], - "ignorePlurals": [
- "ca",
- "es"
], - "removeStopWords": [
- "ca",
- "es"
], - "keepDiacriticsOnCharacters": "øé",
- "queryLanguages": [
- "es"
], - "decompoundQuery": true,
- "enableRules": true,
- "enablePersonalization": false,
- "queryType": "prefixAll",
- "removeWordsIfNoResults": "firstWords",
- "mode": "keywordSearch",
- "semanticSearch": {
- "eventSources": [
- "string"
]
}, - "advancedSyntax": false,
- "optionalWords": [
- "blue",
- "iphone case"
], - "disableExactOnAttributes": [
- "description"
], - "exactOnSingleWordQuery": "attribute",
- "alternativesAsExact": [
- "ignorePlurals",
- "singleWordSynonym"
], - "advancedSyntaxFeatures": [
- "exactPhrase",
- "excludeWords"
], - "distinct": 1,
- "replaceSynonymsInHighlight": false,
- "minProximity": 1,
- "responseFields": [
- "*"
], - "maxFacetHits": 10,
- "maxValuesPerFacet": 100,
- "sortFacetValuesBy": "count",
- "attributeCriteriaComputedByMinProximity": false,
- "renderingContent": {
- "facetOrdering": {
- "facets": {
- "order": [
- "string"
]
}, - "values": {
- "facet1": {
- "order": [
- "string"
], - "sortRemainingBy": "alpha"
}, - "facet2": {
- "order": [
- "string"
], - "sortRemainingBy": "alpha"
}
}
}
}, - "enableReRanking": true,
- "reRankingApplyFilter": [
- [
- "string"
]
], - "query": {
- "remove": [
- "string"
], - "edits": [
- {
- "type": "remove",
- "delete": "string",
- "insert": "string"
}
]
}, - "automaticFacetFilters": [
- {
- "facet": "string",
- "score": 1,
- "disjunctive": false
}
], - "automaticOptionalFacetFilters": [
- {
- "facet": "string",
- "score": 1,
- "disjunctive": false
}
]
}, - "promote": [
- {
- "objectIDs": [
- "string"
], - "position": 0
}
], - "filterPromotes": false,
- "hide": [
- {
- "objectID": "string"
}
], - "userData": {
- "settingID": "f2a7b51e3503acc6a39b3784ffb84300",
- "pluginVersion": "1.6.0"
}
}, - "description": "Display a promotional banner",
- "enabled": true
}
Delete a Recommend rule.
Delete a Recommend rule.
path Parameters
indexName required | string Example: YourIndexName Name of the index on which to perform the operation. |
model required | string Enum: "bought-together" "related-products" "trending-facets" "trending-items" |
objectID required | string Example: 123 Unique record identifier. |
Responses
Request samples
- C#
- Dart
- Go
- Java
- JavaScript
- Kotlin
- PHP
- Python
- Ruby
- Scala
- Swift
// Initialize the client var client = new RecommendClient(new RecommendConfig("YOUR_APP_ID", "YOUR_API_KEY")); // Call the API var response = await client.DeleteRecommendRuleAsync( "indexName", Enum.Parse<RecommendModels>("RelatedProducts"), "objectID" );
Response samples
- 200
- 400
- 402
- 403
- 404
{- "taskID": 1514562690001,
- "deletedAt": "2023-06-27T14:42:38.831Z"
}
Get a Recommend task's status.
Some operations, such as deleting a Recommend rule, will respond with a taskID
value. Use this value here to check the status of that task.
path Parameters
indexName required | string Example: YourIndexName Name of the index on which to perform the operation. |
model required | string Enum: "bought-together" "related-products" "trending-facets" "trending-items" |
taskID required | integer <int64> Example: 13235 Unique identifier of a task. Numeric value (up to 64bits). |
Responses
Request samples
- C#
- Dart
- Go
- Java
- JavaScript
- Kotlin
- PHP
- Python
- Ruby
- Scala
- Swift
// Initialize the client var client = new RecommendClient(new RecommendConfig("YOUR_APP_ID", "YOUR_API_KEY")); // Call the API var response = await client.GetRecommendStatusAsync( "indexName", Enum.Parse<RecommendModels>("RelatedProducts"), 12345L );
Response samples
- 200
- 400
- 402
- 403
- 404
{- "status": "notPublished"
}
List Recommend rules.
List Recommend rules.
path Parameters
indexName required | string Example: YourIndexName Name of the index on which to perform the operation. |
model required | string Enum: "bought-together" "related-products" "trending-facets" "trending-items" |
Request Body schema: application/json
context | string Restricts responses to the specified contextual rule. |
boolean or null | |
hitsPerPage | integer [ 1 .. 1000 ] Default: 20 Maximum number of hits per page. |
page | integer >= 0 Requested page of the API response. |
query | string Default: "" Search query. |
Responses
Request samples
- C#
- Dart
- Go
- Java
- JavaScript
- Kotlin
- PHP
- Python
- Ruby
- Scala
- Swift
// Initialize the client var client = new RecommendClient(new RecommendConfig("YOUR_APP_ID", "YOUR_API_KEY")); // Call the API var response = await client.SearchRecommendRulesAsync( "indexName", Enum.Parse<RecommendModels>("RelatedProducts") );
Response samples
- 200
- 400
- 402
- 403
- 404
{- "hits": [
- {
- "_metadata": {
- "lastUpdate": "2023-07-04T12:49:15Z"
}, - "objectID": "hide-12345",
- "conditions": [
- {
- "pattern": "{facet:genre}",
- "anchoring": "contains",
- "alternatives": false,
- "context": "mobile",
- "filters": "genre:comedy"
}
], - "consequence": {
- "params": {
- "similarQuery": "comedy drama crime Macy Buscemi",
- "filters": "(category:Book OR category:Ebook) AND _tags:published",
- "facetFilters": [
- [
- "category:Book",
- "category:-Movie"
], - "author:John Doe"
], - "optionalFilters": [
- "category:Book",
- "author:John Doe"
], - "numericFilters": [
- [
- "inStock = 1",
- "deliveryDate < 1441755506"
], - "price < 1000"
], - "tagFilters": [
- [
- "Book",
- "Movie"
], - "SciFi"
], - "sumOrFiltersScores": false,
- "restrictSearchableAttributes": [
- "title",
- "author"
], - "facets": [
- "*"
], - "facetingAfterDistinct": false,
- "page": 0,
- "offset": 0,
- "length": 1,
- "aroundLatLng": "40.71,-74.01",
- "aroundLatLngViaIP": false,
- "aroundRadius": 1,
- "aroundPrecision": 10,
- "minimumAroundRadius": 1,
- "insideBoundingBox": [
- [
- 47.3165,
- 4.9665,
- 47.3424,
- 5.0201
], - [
- 40.9234,
- 2.1185,
- 38.643,
- 1.9916
]
], - "insidePolygon": [
- [
- 47.3165,
- 4.9665,
- 47.3424,
- 5.0201,
- 47.32,
- 4.9
], - [
- 40.9234,
- 2.1185,
- 38.643,
- 1.9916,
- 39.2587,
- 2.0104
]
], - "naturalLanguages": [ ],
- "ruleContexts": [
- "mobile"
], - "personalizationImpact": 100,
- "userToken": "test-user-123",
- "getRankingInfo": false,
- "synonyms": true,
- "clickAnalytics": false,
- "analytics": true,
- "analyticsTags": [ ],
- "percentileComputation": true,
- "enableABTest": true,
- "attributesToRetrieve": [
- "author",
- "title",
- "content"
], - "ranking": [
- "typo",
- "geo",
- "words",
- "filters",
- "proximity",
- "attribute",
- "exact",
- "custom"
], - "customRanking": [
- "desc(popularity)",
- "asc(price)"
], - "relevancyStrictness": 90,
- "attributesToHighlight": [
- "author",
- "title",
- "conten",
- "content"
], - "attributesToSnippet": [
- "content:80",
- "description"
], - "highlightPreTag": "<em>",
- "highlightPostTag": "</em>",
- "snippetEllipsisText": "…",
- "restrictHighlightAndSnippetArrays": false,
- "hitsPerPage": 20,
- "minWordSizefor1Typo": 4,
- "minWordSizefor2Typos": 8,
- "typoTolerance": true,
- "allowTyposOnNumericTokens": true,
- "disableTypoToleranceOnAttributes": [
- "sku"
], - "ignorePlurals": [
- "ca",
- "es"
], - "removeStopWords": [
- "ca",
- "es"
], - "keepDiacriticsOnCharacters": "øé",
- "queryLanguages": [
- "es"
], - "decompoundQuery": true,
- "enableRules": true,
- "enablePersonalization": false,
- "queryType": "prefixAll",
- "removeWordsIfNoResults": "firstWords",
- "mode": "keywordSearch",
- "semanticSearch": {
- "eventSources": [
- "string"
]
}, - "advancedSyntax": false,
- "optionalWords": [
- "blue",
- "iphone case"
], - "disableExactOnAttributes": [
- "description"
], - "exactOnSingleWordQuery": "attribute",
- "alternativesAsExact": [
- "ignorePlurals",
- "singleWordSynonym"
], - "advancedSyntaxFeatures": [
- "exactPhrase",
- "excludeWords"
], - "distinct": 1,
- "replaceSynonymsInHighlight": false,
- "minProximity": 1,
- "responseFields": [
- "*"
], - "maxFacetHits": 10,
- "maxValuesPerFacet": 100,
- "sortFacetValuesBy": "count",
- "attributeCriteriaComputedByMinProximity": false,
- "renderingContent": {
- "facetOrdering": {
- "facets": {
- "order": [
- "string"
]
}, - "values": {
- "facet1": {
- "order": [
- null
], - "sortRemainingBy": "alpha"
}, - "facet2": {
- "order": [
- null
], - "sortRemainingBy": "alpha"
}
}
}
}, - "enableReRanking": true,
- "reRankingApplyFilter": [
- [
- "string"
]
], - "query": {
- "remove": [
- "string"
], - "edits": [
- {
- "type": "remove",
- "delete": "string",
- "insert": "string"
}
]
}, - "automaticFacetFilters": [
- {
- "facet": "string",
- "score": 1,
- "disjunctive": false
}
], - "automaticOptionalFacetFilters": [
- {
- "facet": "string",
- "score": 1,
- "disjunctive": false
}
]
}, - "promote": [
- {
- "objectIDs": [
- "string"
], - "position": 0
}
], - "filterPromotes": false,
- "hide": [
- {
- "objectID": "string"
}
], - "userData": {
- "settingID": "f2a7b51e3503acc6a39b3784ffb84300",
- "pluginVersion": "1.6.0"
}
}, - "description": "Display a promotional banner",
- "enabled": true
}
], - "nbHits": 20,
- "page": 0,
- "nbPages": 1
}