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

Front-end libraries

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

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

Description:

Returns recommendations for a specific model.

Parameters:

{
  indexName: "an index name",
  model: "bought-together",
  threshold: 0,
  maxRecommendations: 10,
  objectID: "an objectID",
  queryParameters: { query parameters },
  fallbackParameters: { query parameters }
}

{
  indexName: "an index name",
  model: "trending-items",
  threshold: 0,
  maxRecommendations: 10,
  facetName: "a facet attribute name",
  facetValue: "a facet value",
  queryParameters: { query parameters },
  fallbackParameters: { query parameters }
}

{
  indexName: "an index name",
  model: "trending-facets",
  threshold: 0,
  maxRecommendations: 10,
  facetName: "a facet attribute name",
}

Errors:

• 401: Unauthorized. The credentials (application ID, API key) are either missing or incorrect.
• 400: InvalidSearchParameters. An Algolia search parameter is invalid.

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"
    }
    // ...
  ]
}