API Reference / REST API / Recommend REST API

This page documents the Algolia Recommend REST API. However, it’s strongly recommend to use Algolia’s official API clients, libraries, and integrations to build your recommendations implementation.

Algolia has developed API clients and libraries for interacting with Algolia recommend. These advanced wrappers handle errors, and enforce the best search practices and optimal use of Algolia Recommend. Everything you can do with the REST API can be done using the API clients and libraries. They’re all open source, and the code is available on GitHub.

You should only use the Recommend REST API to develop new API clients. There’s no SLA if you use the REST API directly.

API clients

JavaScript

Front-end libraries

JavaScript

Hosts

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

The primary host is {Application-ID}-dsn.algolia.net. The *-dsn host guarantees high availability through automatic load balancing and also leverages Algolia’s Distributed Search Network (if you subscribed that option).

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

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

Format

The entire API uses JSON encoded in UTF-8.

The body of POST and PUT requests must be a JSON object and their Content-Type header should be set to application/json; charset=UTF-8.

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

Parameters

Unless otherwise stated, you must pass parameters:

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

You must URL-encode parameters passed in the URL using the UTF-8 encoding for non-ASCII characters. The plus character (+) is interpreted as a space, so it’s an alternative to %20.

Authentication

To authenticate, you need to pass the following HTTP headers:

  • X-Algolia-Application-Id identifies which Algolia application you’re accessing
  • X-Algolia-API-Key authenticates endpoint access

The X-Algolia-API-Key needs to have the search ACL.

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

Error handling

The HTTP status code indicates whether a request succeeded or failed. A 2xx status code indicates success, whereas a 4xx status code indicates failure.

When a request fails, the response body is still JSON with contains a message field containing a description of the error, which you can inspect for debugging. For example, trying to retrieve recommendations with an invalid API key returns the message:

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

Endpoints

Quick Reference

Verb Path Method

POST

/1/indexes/*/recommendations

Get Recommendations

Get Recommendations

A

Path: /1/indexes/*/recommendations
HTTP Verb: POST

Description:

Returns recommendations for a specific model and objectID.

Parameters:

requests
type: array
Required

A list of recommendation requests to execute.

requests ➔ request object

{
  indexName: "an index name",
  model: "a model",
  objectID: "an objectID",
  threshold: 0,
  maxRecommendations: 10,
  queryParameters: { query parameters },
  fallbackParameters: { query parameters }
}
indexName
type: string
Required

Name of the index to target.

model
type: string
Required

The recommendation model to use, one of:

  • related-products
  • bought-together
objectID
type: string
Required

The objectID to get recommendations for.

threshold
type: number
default: 0
Optional

The threshold to use when filtering recommendations by their score.

maxRecommendations
type: number
default: 3 for FBT, 25 for RP
Optional

The maximum number of recommendations to retrieve.

queryParameters
type: key-value mapping
Optional

A key-value mapping of search parameters to filter the recommendations.

fallbackParameters
type: key-value mapping
Optional

A key-value mapping of search parameters to use as fallback when there are no recommendations.

Errors:

Example:

A

1
2
3
4
5
6
7
8
9
10
11
12
13
curl -X POST https://${APPLICATION_ID}-dsn.algolia.net/1/indexes/*/recommendations \
     -H 'Content-Type: application/json' \
     -H 'X-Algolia-Api-Key: ${API_KEY_WITH_SEARCH_ACL}' \
     -H 'X-Algolia-Application-ID: ${APPLICATION_ID}' \
     -d '{
       "requests": [
         {
           "indexName": "index1",
           "model": "related-products",
           "objectID": "objectID1"
         }
       ]
     }'

Response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
  "results": [
    {
      "hits": [
        {
          "objectID": "objectID1",
          "_score": 0.42
          // ...
        },
        {
          "objectID": "objectID2",
          "_score": 0.21
          // ...
        }
        //...
      ],
      "nbHits": 42,
      "queryID": "43b15df305339e827f0ac0bdc5ebcaa7"
    }
    // ...
  ]
}

Did you find this page helpful?