Retrieve recommendations

Retrieves recommendations from selected AI models.

POST /1/indexes/*/recommendations

curl

cURL

curl --request POST \
  --url 'https://algolia_application_id.algolia.net/1/indexes/*/recommendations' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'x-algolia-api-key: ALGOLIA_API_KEY' \
  --header 'x-algolia-application-id: ALGOLIA_APPLICATION_ID' \
  --data '
{
  "requests": [
    {
      "indexName": "products",
      "threshold": 0,
      "maxRecommendations": 30,
      "queryParameters": {
        "similarQuery": "comedy drama crime Macy Buscemi",
        "filters": "(category:Book OR category:Ebook) AND _tags:published",
        "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,
        "aroundLatLng": "40.71,-74.01",
        "aroundLatLngViaIP": false,
        "aroundRadius": 1,
        "aroundPrecision": 10,
        "minimumAroundRadius": 1,
        "insideBoundingBox": "lorem",
        "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,
        "query": "",
        "attributesForFaceting": [
          "author",
          "filterOnly(isbn)",
          "searchable(edition)",
          "afterDistinct(category)",
          "afterDistinct(searchable(publisher))"
        ],
        "replicas": [
          "virtual(prod_products_price_asc)",
          "dev_products_replica"
        ],
        "paginationLimitedTo": 100,
        "unretrievableAttributes": [
          "total_sales"
        ],
        "disableTypoToleranceOnWords": [
          "wheel",
          "1X2BCD"
        ],
        "attributesToTransliterate": [
          "name",
          "description"
        ],
        "camelCaseAttributes": [
          "description"
        ],
        "decompoundedAttributes": {
          "de": [
            "name"
          ]
        },
        "indexLanguages": [
          "ja"
        ],
        "disablePrefixOnAttributes": [
          "sku"
        ],
        "allowCompressionOfIntegerArray": false,
        "numericAttributesForFiltering": [
          "equalOnly(quantity)",
          "popularity"
        ],
        "separatorsToIndex": "+#",
        "searchableAttributes": [
          "title,alternative_title",
          "author",
          "unordered(text)",
          "emails.personal"
        ],
        "userData": {
          "settingID": "f2a7b51e3503acc6a39b3784ffb84300",
          "pluginVersion": "1.6.0"
        },
        "customNormalization": {
          "default": {
            "ä": "ae",
            "ü": "ue"
          }
        },
        "attributeForDistinct": "url",
        "maxFacetHits": 10,
        "keepDiacriticsOnCharacters": "øé",
        "customRanking": [
          "desc(popularity)",
          "asc(price)"
        ],
        "attributesToRetrieve": [
          "author",
          "title",
          "content"
        ],
        "relevancyStrictness": 90,
        "attributesToHighlight": [
          "author",
          "title",
          "conten",
          "content"
        ],
        "attributesToSnippet": [
          "content:80",
          "description"
        ],
        "highlightPreTag": "<em>",
        "highlightPostTag": "</em>",
        "snippetEllipsisText": "…",
        "restrictHighlightAndSnippetArrays": false,
        "minWordSizefor1Typo": 4,
        "minWordSizefor2Typos": 8,
        "typoTolerance": true,
        "allowTyposOnNumericTokens": true,
        "disableTypoToleranceOnAttributes": [
          "sku"
        ],
        "ignorePlurals": [
          "ca",
          "es"
        ],
        "removeStopWords": [
          "ca",
          "es"
        ],
        "queryLanguages": [
          "es"
        ],
        "decompoundQuery": true,
        "enablePersonalization": false,
        "queryType": "prefixLast",
        "removeWordsIfNoResults": "firstWords",
        "advancedSyntax": false,
        "optionalWords": "lorem",
        "disableExactOnAttributes": [
          "description"
        ],
        "exactOnSingleWordQuery": "attribute",
        "alternativesAsExact": [
          "ignorePlurals",
          "singleWordSynonym"
        ],
        "advancedSyntaxFeatures": [
          "exactPhrase",
          "excludeWords"
        ],
        "distinct": 1,
        "replaceSynonymsInHighlight": false,
        "minProximity": 1,
        "responseFields": [
          "*"
        ],
        "maxValuesPerFacet": 100,
        "sortFacetValuesBy": "count",
        "attributeCriteriaComputedByMinProximity": false,
        "renderingContent": {
          "facetOrdering": {
            "facets": {
              "order": [
                "lorem"
              ]
            },
            "values": {
              "property1": {
                "order": [
                  "lorem"
                ],
                "sortRemainingBy": "count",
                "hide": [
                  "lorem"
                ]
              },
              "property2": {
                "order": [
                  "lorem"
                ],
                "sortRemainingBy": "count",
                "hide": [
                  "lorem"
                ]
              }
            }
          },
          "redirect": {
            "url": "lorem"
          },
          "widgets": {
            "banners": [
              {
                "image": {
                  "urls": [
                    {
                      "url": "lorem"
                    }
                  ],
                  "title": "lorem"
                },
                "link": {
                  "url": "lorem"
                }
              }
            ]
          }
        },
        "enableReRanking": true,
        "reRankingApplyFilter": [
          []
        ],
        "enableRules": true
      },
      "model": "bought-together",
      "objectID": "test-record-123",
      "fallbackParameters": {
        "similarQuery": "comedy drama crime Macy Buscemi",
        "filters": "(category:Book OR category:Ebook) AND _tags:published",
        "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,
        "aroundLatLng": "40.71,-74.01",
        "aroundLatLngViaIP": false,
        "aroundRadius": 1,
        "aroundPrecision": 10,
        "minimumAroundRadius": 1,
        "insideBoundingBox": "lorem",
        "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,
        "query": "",
        "attributesForFaceting": [
          "author",
          "filterOnly(isbn)",
          "searchable(edition)",
          "afterDistinct(category)",
          "afterDistinct(searchable(publisher))"
        ],
        "replicas": [
          "virtual(prod_products_price_asc)",
          "dev_products_replica"
        ],
        "paginationLimitedTo": 100,
        "unretrievableAttributes": [
          "total_sales"
        ],
        "disableTypoToleranceOnWords": [
          "wheel",
          "1X2BCD"
        ],
        "attributesToTransliterate": [
          "name",
          "description"
        ],
        "camelCaseAttributes": [
          "description"
        ],
        "decompoundedAttributes": {
          "de": [
            "name"
          ]
        },
        "indexLanguages": [
          "ja"
        ],
        "disablePrefixOnAttributes": [
          "sku"
        ],
        "allowCompressionOfIntegerArray": false,
        "numericAttributesForFiltering": [
          "equalOnly(quantity)",
          "popularity"
        ],
        "separatorsToIndex": "+#",
        "searchableAttributes": [
          "title,alternative_title",
          "author",
          "unordered(text)",
          "emails.personal"
        ],
        "userData": {
          "settingID": "f2a7b51e3503acc6a39b3784ffb84300",
          "pluginVersion": "1.6.0"
        },
        "customNormalization": {
          "default": {
            "ä": "ae",
            "ü": "ue"
          }
        },
        "attributeForDistinct": "url",
        "maxFacetHits": 10,
        "keepDiacriticsOnCharacters": "øé",
        "customRanking": [
          "desc(popularity)",
          "asc(price)"
        ],
        "attributesToRetrieve": [
          "author",
          "title",
          "content"
        ],
        "relevancyStrictness": 90,
        "attributesToHighlight": [
          "author",
          "title",
          "conten",
          "content"
        ],
        "attributesToSnippet": [
          "content:80",
          "description"
        ],
        "highlightPreTag": "<em>",
        "highlightPostTag": "</em>",
        "snippetEllipsisText": "…",
        "restrictHighlightAndSnippetArrays": false,
        "minWordSizefor1Typo": 4,
        "minWordSizefor2Typos": 8,
        "typoTolerance": true,
        "allowTyposOnNumericTokens": true,
        "disableTypoToleranceOnAttributes": [
          "sku"
        ],
        "ignorePlurals": [
          "ca",
          "es"
        ],
        "removeStopWords": [
          "ca",
          "es"
        ],
        "queryLanguages": [
          "es"
        ],
        "decompoundQuery": true,
        "enablePersonalization": false,
        "queryType": "prefixLast",
        "removeWordsIfNoResults": "firstWords",
        "advancedSyntax": false,
        "optionalWords": "lorem",
        "disableExactOnAttributes": [
          "description"
        ],
        "exactOnSingleWordQuery": "attribute",
        "alternativesAsExact": [
          "ignorePlurals",
          "singleWordSynonym"
        ],
        "advancedSyntaxFeatures": [
          "exactPhrase",
          "excludeWords"
        ],
        "distinct": 1,
        "replaceSynonymsInHighlight": false,
        "minProximity": 1,
        "responseFields": [
          "*"
        ],
        "maxValuesPerFacet": 100,
        "sortFacetValuesBy": "count",
        "attributeCriteriaComputedByMinProximity": false,
        "renderingContent": {
          "facetOrdering": {
            "facets": {
              "order": [
                "lorem"
              ]
            },
            "values": {
              "property1": {
                "order": [
                  "lorem"
                ],
                "sortRemainingBy": "count",
                "hide": [
                  "lorem"
                ]
              },
              "property2": {
                "order": [
                  "lorem"
                ],
                "sortRemainingBy": "count",
                "hide": [
                  "lorem"
                ]
              }
            }
          },
          "redirect": {
            "url": "lorem"
          },
          "widgets": {
            "banners": [
              {
                "image": {
                  "urls": [
                    {
                      "url": "lorem"
                    }
                  ],
                  "title": "lorem"
                },
                "link": {
                  "url": "lorem"
                }
              }
            ]
          }
        },
        "enableReRanking": true,
        "reRankingApplyFilter": [
          []
        ],
        "facetFilters": [
          [
            "category:Book",
            "category:-Movie"
          ],
          "author:John Doe"
        ]
      }
    }
  ]
}
'

// Initialize the client
var client = new RecommendClient(
  new RecommendConfig("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY")
);

// Call the API
var response = await client.GetRecommendationsAsync(
  new GetRecommendationsParams
  {
    Requests = new List<RecommendationsRequest>
    {
      new RecommendationsRequest(
        new RelatedQuery
        {
          IndexName = "<YOUR_INDEX_NAME>",
          ObjectID = "objectID",
          Model = Enum.Parse<RelatedModel>("RelatedProducts"),
          Threshold = 42.1,
        }
      ),
    },
  }
);

// print the response
Console.WriteLine(response);

// Initialize the client
final client = RecommendClient(
    appId: 'ALGOLIA_APPLICATION_ID', apiKey: 'ALGOLIA_API_KEY');

// Call the API
final response = await client.getRecommendations(
  getRecommendationsParams: GetRecommendationsParams(
    requests: [
      RelatedQuery(
        indexName: "<YOUR_INDEX_NAME>",
        objectID: "objectID",
        model: RelatedModel.fromJson("related-products"),
        threshold: 42.1,
      ),
    ],
  ),
);

// print the response
print(response);

// Initialize the client
client, err := recommend.NewClient("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY")
if err != nil {
  // The client can fail to initialize if you pass an invalid parameter.
  panic(err)
}

// Call the API
response, err := client.GetRecommendations(client.NewApiGetRecommendationsRequest(

  recommend.NewEmptyGetRecommendationsParams().SetRequests(
    []recommend.RecommendationsRequest{*recommend.RelatedQueryAsRecommendationsRequest(
      recommend.NewEmptyRelatedQuery().SetIndexName("<YOUR_INDEX_NAME>").SetObjectID("objectID").SetModel(recommend.RelatedModel("related-products")).SetThreshold(42.1))})))
if err != nil {
  // handle the eventual error
  panic(err)
}


// print the response
print(response)

// Initialize the client
RecommendClient client = new RecommendClient("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY");

// Call the API
GetRecommendationsResponse response = client.getRecommendations(
  new GetRecommendationsParams().setRequests(
    Arrays.asList(
      new RelatedQuery()
        .setIndexName("<YOUR_INDEX_NAME>")
        .setObjectID("objectID")
        .setModel(RelatedModel.RELATED_PRODUCTS)
        .setThreshold(42.1)
    )
  )
);

// print the response
System.out.println(response);

// Initialize the client
const client = algoliasearch('ALGOLIA_APPLICATION_ID', 'ALGOLIA_API_KEY').initRecommend();

// Call the API
const response = await client.getRecommendations({
  requests: [{ indexName: 'indexName', objectID: 'objectID', model: 'related-products', threshold: 42.1 }],
});


// print the response
console.log(response);

// Initialize the client
val client = RecommendClient(appId = "ALGOLIA_APPLICATION_ID", apiKey = "ALGOLIA_API_KEY")

// Call the API
var response =
  client.getRecommendations(
    getRecommendationsParams =
      GetRecommendationsParams(
        requests =
          listOf(
            RelatedQuery(
              indexName = "<YOUR_INDEX_NAME>",
              objectID = "objectID",
              model = RelatedModel.entries.first { it.value == "related-products" },
              threshold = 42.1,
            )
          )
      )
  )


// print the response
println(response)

// Initialize the client
$client = RecommendClient::create('ALGOLIA_APPLICATION_ID', 'ALGOLIA_API_KEY');

// Call the API
$response = $client->getRecommendations(
    ['requests' => [
        ['indexName' => '<YOUR_INDEX_NAME>',
            'objectID' => 'objectID',
            'model' => 'related-products',
            'threshold' => 42.1,
        ],
    ],
    ],
);


// print the response
var_dump($response);

# Initialize the client
# In an asynchronous context, you can use RecommendClient instead, which exposes the exact same methods.
client = RecommendClientSync("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY")

# Call the API
response = client.get_recommendations(
    get_recommendations_params={
        "requests": [
            {
                "indexName": "<YOUR_INDEX_NAME>",
                "objectID": "objectID",
                "model": "related-products",
                "threshold": 42.1,
            },
        ],
    },
)


# print the response
print(response)

# Initialize the client
client = Algolia::RecommendClient.create("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY")

# Call the API
response = client.get_recommendations(
  Algolia::Recommend::GetRecommendationsParams.new(
    requests: [
      Algolia::Recommend::RelatedQuery.new(
        index_name: "<YOUR_INDEX_NAME>",
        algolia_object_id: "objectID",
        model: "related-products",
        threshold: 42.1
      )
    ]
  )
)


# print the response
puts(response)

// Initialize the client
val client = RecommendClient(appId = "ALGOLIA_APPLICATION_ID", apiKey = "ALGOLIA_API_KEY")

// Call the API
val response = Await.result(
  client.getRecommendations(
    getRecommendationsParams = GetRecommendationsParams(
      requests = Seq(
        RelatedQuery(
          indexName = "<YOUR_INDEX_NAME>",
          objectID = "objectID",
          model = RelatedModel.withName("related-products"),
          threshold = 42.1
        )
      )
    )
  ),
  Duration(100, "sec")
)

// print the response
println(response)

// Initialize the client
let client = try RecommendClient(appID: "ALGOLIA_APPLICATION_ID", apiKey: "ALGOLIA_API_KEY")

// Call the API
let response = try await client
    .getRecommendations(getRecommendationsParams: GetRecommendationsParams(requests: [RecommendationsRequest
            .relatedQuery(RelatedQuery(
                indexName: "<YOUR_INDEX_NAME>",
                threshold: 42.1,
                model: RelatedModel.relatedProducts,
                objectID: "objectID"
            ))]))

// print the response
print(response)

200

{
  "results": [
    {
      "hits": [
        {
          "objectID": "test-record-123",
          "_distinctSeqID": 123,
          "_highlightResult": {},
          "_rankingInfo": {
            "firstMatchedWord": 1,
            "geoDistance": 1,
            "nbExactWords": 1,
            "nbTypos": 1,
            "userScore": 123,
            "filters": 1,
            "geoPrecision": 2,
            "matchedGeoLocation": {
              "distance": 123,
              "lat": 123,
              "lng": 123
            },
            "personalization": {
              "filtersScore": 123,
              "rankingScore": 123,
              "score": 123
            },
            "promoted": true,
            "promotedByReRanking": true,
            "proximityDistance": 1,
            "words": 2
          },
          "_score": 50,
          "_snippetResult": {}
        }
      ],
      "_automaticInsights": true,
      "abTestID": 123,
      "abTestVariantID": 2,
      "appliedRules": [
        {}
      ],
      "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": {},
      "index": "indexName",
      "indexUsed": "indexNameAlt",
      "message": "<string>",
      "nbSortedHits": 20,
      "parsedQuery": "george clo",
      "processingTimeMS": 20,
      "processingTimingsMS": {},
      "queryAfterRemoval": "<string>",
      "queryID": "a00dbc80a8d13c4565a442e7e2dca80a",
      "redirect": {
        "index": [
          {
            "data": {
              "ruleObjectID": "<string>"
            },
            "dest": "<string>",
            "reason": "<string>",
            "source": "<string>",
            "succeed": true
          }
        ]
      },
      "renderingContent": {
        "facetOrdering": {
          "facets": {
            "order": [
              "<string>"
            ]
          },
          "values": {}
        },
        "redirect": {
          "url": "<string>"
        },
        "widgets": {
          "banners": [
            {
              "image": {
                "title": "<string>",
                "urls": [
                  {
                    "url": "<string>"
                  }
                ]
              },
              "link": {
                "url": "<string>"
              }
            }
          ]
        }
      },
      "serverTimeMS": 20,
      "serverUsed": "c2-uk-3.algolia.net",
      "userData": {
        "settingID": "f2a7b51e3503acc6a39b3784ffb84300",
        "pluginVersion": "1.6.0"
      },
      "hitsPerPage": 20,
      "nbHits": 20,
      "nbPages": 1,
      "page": 0
    }
  ]
}

{
  "message": "Invalid Application-Id or API-Key"
}

{
  "message": "Invalid Application-Id or API-Key"
}

{
  "message": "Invalid Application-Id or API-Key"
}

{
  "message": "Invalid Application-Id or API-Key"
}

Required ACL: search

Authorizations

x-algolia-application-id · string · header · required

Your Algolia application ID.

x-algolia-api-key · string · header · required

Your Algolia API key with the necessary permissions to make the request. Permissions are controlled through access control lists (ACL) and access restrictions. The required ACL to make a request is listed in each endpoint's reference.

Body

application/json

Recommend request body.

requests · (Frequently bought together · object | Related products · object | Trending items · object | Trending facet values · object | Looking similar · object)[] · required

Recommendation request with parameters depending on the requested model.

Frequently bought together

Related products

Trending items

Trending facet values

Looking similar

Show child attributes

Response

200

application/json

OK

results · object[] · required

Show child attributes