API Reference / REST API / Recommend REST API

Aug. 12, 2022

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

PHP

JavaScript

Python

CSharp

Java

Scala

Kotlin

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:

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

Endpoints

Quick Reference

Verb	Path	Method
POST	/1/indexes/*/recommendations	Get Recommendations
POST	/1/indexes/`{indexName}`/`{model}`/recommend/rules/batch	Batch Recommend Rules (beta)
GET	/1/indexes/`{indexName}`/`{model}`/recommend/rules/`{objectID}`	Get Recommend Rule (beta)
DELETE	/1/indexes/`{indexName}`/`{model}`/recommend/rules/`{objectID}`	Delete Recommend Rule (beta)
POST	/1/indexes/`{indexName}`/`{model}`/recommend/rules/search	Search Recommend Rules (beta)
GET	/1/indexes/`{indexName}`/`{model}`/task/`{taskID}`	Get a Recommend task's status (beta)

Get Recommendations

Path: /1/indexes/*/recommendations
HTTP Verb: POST
Required API Key: any key with the search ACL

Description:

Returns recommendations for a specific model.

Parameters:


            requests

type: array

Required

A list of recommendation requests to execute.

requests ➔ request object

A single recommendation request. The body schema depends on the targeted model. The following parameters are common to all models.

`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` `trending-items` `trending-facets`
`threshold`	type: number Required The threshold to use when filtering recommendations by their score. The value must be between 0 and 100.
`maxRecommendations`	type: number default: 0 Optional The number of recommendations to retrieve. Depending on the available recommendations and the other request parameters, the actual number of hits may be lower than that. If `maxRecommendations` isn’t provided or set to 0, all matching recommendations are returned, and no fallback request is performed.

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

Fetch recommendations of a specific item. The following parameters are specific to models ‘related-products’ and ‘bought-together’.

`objectID`	type: string Required The `objectID` to get recommendations for.
`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.

{
  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 }
}

Fetch trending items, either globally or only those matching a specific facet. The following parameters are specific to model ‘trending-items’. If no facet is provided, the query fetches globally trending items.

`facetName`	type: string Optional The facet attribute to get recommendations for. This parameter must be used along with facetValue.
`facetValue`	type: string Optional The facet value to get recommendations for. This parameter must be used along with facetName.
`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.

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

Fetch trending facet values given a specific facet attribute. The following parameters are specific to model ‘trending-facets’.


            facetName

type: string

Required

The facet attribute to get recommendations for.

Errors:

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

Example:

Copy
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:

Copy
{
  "results": [
    {
      "hits": [
        {
          "objectID": "objectID1",
          "_score": 0.42
          // ...
        },
        {
          "objectID": "objectID2",
          "_score": 0.21
          // ...
        }
        //...
      ],
      "nbHits": 42,
      "queryID": "43b15df305339e827f0ac0bdc5ebcaa7"
    }
    // ...
  ]
}

Path: /1/indexes/{indexName}/{model}/recommend/rules/batch
HTTP Verb: POST
Required API Key: any key with the editSettings ACL

Description:

This endpoint is in beta.

Create or update a batch of Recommend Rules.

Each Recommend Rule is created or updated, depending on whether a Recommend Rule with the same objectID already exists. You may also specify true for clearExistingRules, in which case the batch will atomically replace all the existing Recommend Rules.

Recommend Rules are similar to Search Rules, except that the conditions and consequences apply to a source item instead of a query. The main differences are the following:

Conditions pattern and anchoring are unavailable.
Condition filters triggers if the source item matches the specified filters.
Condition filters accepts numeric filters.
Consequence params only covers filtering parameters.
Consequence automaticFacetFilters doesn’t require a facet value placeholder (it tries to match the data source item’s attributes instead).

Parameters:

`indexName`	type: string Required Index name
`model`	type: string Required Model name
`clearExistingRules`	type: boolean default: false Optional Use as a URL query string, not in the body. When `true`, existing Rules are cleared before adding this batch. When `false`, existing Rules are kept.
`Rules`	type: list of rule Optional A list of rule objects. [ { objectID: objectID, condition: condition, consequence: consequence } ]

Rules ➔ rule

`objectID`	type: string Required Unique identifier for the Rule (format: `[A-Za-z0-9_-]+`).
`condition`	type: condition Optional Condition that should apply to activate a Rule. When the condition isn’t provided or is empty, the Rule is active for all requests to the relevant index and model. { "context": context, "filters": filters }
`consequence`	type: consequence Required Consequence of the Rule (this can’t be an empty value).
`description`	type: string Optional This field is intended for Rule management purposes, in particular to ease searching for Rules and presenting them to human readers. It’s not interpreted by the API.
`enabled`	type: boolean default: true Optional Whether the Rule is enabled. Disabled Rules remain in the index but aren’t applied at query time.
`validity`	type: list of timeRange Optional By default, Rules are permanently valid. When validity periods are specified, the Rule applies only during those periods; it’s ignored the rest of the time. The list must not be empty.

Rules ➔ rule ➔ condition

`context`	type: string Optional Rule context (format: `[A-Za-z0-9_-]+`). When specified, the Rule is only applied when the same context is specified at query time (using the `ruleContexts` parameter). When absent, the Rule is generic and always applies (provided that its other conditions are met).
`filters`	type: string Optional When specified, the Rule is only applied when the source item matches the filters. The syntax is the same as `filters` and it supports the same feature set.

Rules ➔ rule ➔ consequence

`params`	type: params Optional Additional search parameters. In Recommend Rules, only filters and parameters affecting the filters are allowed: `numericFilters`, `tagFilters`, `facetFilters`, `filters`, `optionalTagFilters`, `optionalFacetFilters`, `optionalFilters`, `automaticFacetFilters`, `automaticOptionalFacetFilters`, `sumOrFiltersScores`. { "automaticFacetFilters": automaticFacetFilters, "automaticOptionalFacetFilters": automaticOptionalFacetFilters }
`promote`	type: list Optional Objects to promote as hits. Each object must contain the following fields: `objectID` or `objectIDs`, `position`. By default, you can promote up to 30 items per rule. { "objectID": objectID, "objectIDs": objectIDs, "position": position }
`hide`	type: list Optional Objects to hide from hits. Each object must contain an `objectID` field. By default, you can hide up to 50 items per rule. { "objectID": objectID }
`userData`	type: object Optional A custom JSON object to append to the `userData` array in the response. This object isn’t interpreted by the API. It’s limited to 1kB of minified JSON.

Rules ➔ rule ➔ consequence ➔ params

`automaticFacetFilters`	type: list of automaticFacetFilter Optional Names of facets to which automatic filtering must be applied. This consequence is ignored if a facet name doesn’t match the source item. You can specify a score for each facet name: `facetName1\<score=5\>, facetName2\<score=1\>`.
`automaticOptionalFacetFilters`	type: object Optional The same syntax as `automaticFacetFilters`, but the engine treats the filters as optional. Behaves like optionalFilters.

Rules ➔ rule ➔ consequence ➔ promote-params

`objectID`	type: string true (unless using objectIDs) Unique identifier of the object to promote.
`objectIDs`	type: string[] true (unless using objectID) An array of unique identifiers of the objects to promote.
`position`	type: integer Required The position to promote the objects to (zero-based). If you pass `objectIDs`, the objects are placed at this position as a group. For example, if you pass four `objectID`s to position `0`, the objects take the first four positions.

Rules ➔ rule ➔ consequence ➔ hide


            objectID

type: string

Required

Unique identifier of the object to hide.

Rules ➔ rule ➔ validity ➔ timeRange

`from`	type: integer Required Lower bound of the time range (Unix timestamp).
`until`	type: integer Required Upper bound of the time range (Unix timestamp).

Rules ➔ rule ➔ consequence ➔ params ➔ automaticFacetFilter

`facet`	type: string Required Attribute to filter on. This must match a facet in the source item.
`score`	type: integer default: 1 Optional The score for the filter. Typically used for optional or disjunctive filters.
`disjunctive`	type: boolean default: false Optional Whether the filter is disjunctive (`true`) or conjunctive (`false`). If the filter applies multiple times because the attribute contains multiple values, the multiple occurrences are combined with an `AND` operator by default (conjunctive mode). If the filter is specified as disjunctive, however, multiple occurrences are combined with an `OR` operator.
`negative`	type: boolean default: false Optional Whether the match is inverted (`true`) or not (`false`).

Example:

Copy
curl -X POST \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}.algolia.net/1/indexes/${indexName}/${model}/recommend/rules/batch" \
    --data-binary '[
      {
        "objectID": "a-recommend-rule-id",
        "condition": {
          "filters": "onSale:true"
        },
        "consequence": {
          "userData": {
            "url": "https://website.com/great-sales"
          }
        }
      },
      {
        "objectID": "a-second-recommend-rule-id",
        "consequence": {
          "params": {
            "promote": [
              {
                "objectID": "alwaysTopRecommendation",
                "position": 0
              }
            ]
          }
        }
      }
    ]'

Response:

Copy
{
  "taskID": 247427180002,
  "updatedAt": "2021-06-04T08:24:55.069Z"
}

Path: /1/indexes/{indexName}/{model}/recommend/rules/{objectID}
HTTP Verb: GET
Required API Key: any key with the settings ACL

Description:

This endpoint is in beta.

Fetch the Recommend Rule with the specified objectID.

Parameters:

`indexName`	type: string Required Index name
`model`	type: string Required Model name
`objectID`	type: string Required objectID of the Rule to retrieve

Example:

Copy
curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}.algolia.net/1/indexes/${indexName}/${model}/recommend/rules/${objectID}"

Response:

Copy
{
  "objectID": "myRule",
  "condition": {
    "context": "mobile"
  },
  "consequence": {
    "params": {
      "promote": [
        {
          "objectID": "myProductID",
          "position": 0
        }
      ]
    }
  }
}

Path: /1/indexes/{indexName}/{model}/recommend/rules/{objectID}
HTTP Verb: DELETE
Required API Key: any key with the editSettings ACL

Description:

This endpoint is in beta.

Delete the Recommend Rule with the specified objectID.

Parameters:

`indexName`	type: string Required Index name
`model`	type: string Required Model name
`objectID`	type: string Required objectID of the Rule to delete

Example:

Copy
curl -X DELETE \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}.algolia.net/1/indexes/${indexName}/${model}/recommend/rules/${objectID}"

Response:

Copy
{
  "taskID": 249200944000,
  "updatedAt": "2021-06-04T08:35:58.984Z"
}

Path: /1/indexes/{indexName}/{model}/recommend/rules/search
HTTP Verb: POST
Required API Key: any key with the settings ACL

Description:

This endpoint is in beta.

Search for Recommend Rules.

Parameters:

`indexName`	type: string Required Index name
`model`	type: string Required Model name
`query`	type: string default: "" Optional Full text query.
`context`	type: string default: Any context Optional Restricts matches to contextual rules with a specific context (exact match).
`page`	type: integer default: 0 Optional Requested page (zero-based).
`hitsPerPage`	type: integer default: 20 Optional Number of hits retrieved per page. Accepted range: [1, 1000].
`enabled`	type: boolean default: none Optional When specified, restricts matches to rules with a specific `enabled` status. When absent, retrieves all the rules, regardless of their `enabled` status.
`requestOptions`	type: key-value mapping default: No request options Optional A mapping of `requestOptions` to send along with the request.

Example:

Copy
curl -X POST \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}.algolia.net/1/indexes/${indexName}/${model}/recommend/rules/search" \
    --data-binary '{"query": "world"}'

Response:

Copy
{
  "hits": [
    {
      "_metadata": {
          "lastUpdate": 0
      },
      "consequence": {
        "userData": {
          "hello": "world"
        }
      },
      "enabled": true,
      "objectID": "myRuleID",
      "_highlightResult": {
        "consequence": {
          "userData": {
            "hello": {
              "value": "<b>world</b>",
              "matchLevel": "full",
              "fullyHighlighted": true,
              "matchedWords": [
                "world"
              ]
            }
          }
        }
      }
    }
  ],
  "nbHits": 1,
  "page": 0,
  "nbPages": 1
}

Path: /1/indexes/{indexName}/{model}/task/{taskID}
HTTP Verb: GET
Required API Key: any key with the editSettings ACL

Description:

This endpoint is in beta.

Check the current status of a given Recommend task. taskID is a numeric value (up to 64 bits).

The response exposes the field status. Its value is published if the task has been processed, notPublished otherwise.

Parameters:

`indexName`	type: string Required Index name
`model`	type: string Required Model name
`taskID`	type: string Required `taskID` of the indexing task to wait for.

Example:

Copy
curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}-dsn.algolia.net/1/indexes/${indexName}/${model}/task/${taskID}

Response:

Copy
{
  "status": "published"
}

Did you find this page helpful?

Recommend REST API

API clients

Front-end libraries

Hosts

Format

Parameters

Authentication

Error handling

Endpoints

Quick Reference

Get Recommendations

requests ➔ request object

requests ➔ request object with related-products or bought-together

requests ➔ request object with trending-items

requests ➔ request object with trending-facets

Batch Recommend Rules (beta)

Rules ➔ rule

Rules ➔ rule ➔ condition

Rules ➔ rule ➔ consequence

Rules ➔ rule ➔ consequence ➔ params

Rules ➔ rule ➔ consequence ➔ promote-params

Rules ➔ rule ➔ consequence ➔ hide

Rules ➔ rule ➔ validity ➔ timeRange

Rules ➔ rule ➔ consequence ➔ params ➔ automaticFacetFilter

Get Recommend Rule (beta)

Delete Recommend Rule (beta)

Search Recommend Rules (beta)

Get a Recommend task’s status (beta)