Recommendation API

Overview

The Recommendation API gives you direct access to the user profiles built from the Personalization strategy.

This is intended for backend usage as a privileged API key is required and could expose your data if used from a frontend implementation. The API is still under development and is subject to change namely on the ACL required (recommendation) and the response format.

Domain

The Recommendation API can be reached from multiple domains, each specific to a region. You should use the domain that matches the region where your analytics data is stored and processed. You can use one of the following domains:

• United States: https://recommendation.us.algolia.com
• Europe: https://recommendation.eu.algolia.com

Request Format

The API requires the application ID and API key to be passed in the following HTTP headers:

• X-Algolia-Application-Id: the application ID.
• X-Algolia-API-Key: the Recommendation API key for a given application ID.

Response Format

The response format for all requests is a JSON object.

Whether a request succeeded is indicated by the HTTP status code. A 2xx status code indicates success, whereas a 4xx or 5xx status code indicates failure. When a request fails, the response body is still JSON, but always contains the field message which you can inspect for debugging purposes.

Recommendation

Quick Reference

Path: /1/profiles/personalization/{userToken}
HTTP Verb: GET

Description:

Get the user profile built from Personalization strategy.

The profile is structured by facet name used in the strategy. Each facet value is mapped to its score. Each score represents the user affinity for a specific facet value given the userToken past events and the Personalization strategy defined. Scores are bounded to 20. The last processed event timestamp is provided using the ISO 8601 format for debugging purposes.

The X-Algolia-API-KEY must contain an API key with the recommendation ACL.

Parameters:

Errors:

• 401: Unauthorized
• 404: Not Found
• 500: Internal Error

1
2
3
4
curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://recommendation.us.algolia.com/1/profiles/personalization/user_1"

When the query is successful, the HTTP response is a 200 OK and returns the current status:

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "userToken": "user_1",
  "lastEventAt": "2019-07-12T10:03:37Z",
  "scores": {
    "category": {
      "comedy": 1,
      "documentary": 10
    },
    "location": {
      "US": 6
    }
  }
}

Path: /1/profiles/{userToken}
HTTP Verb: DELETE

Description:

Delete the user profile and all its associated data.

Returns, as part of the response, a date until which the data can safely be considered as deleted for the given user. This means that if you send events for the given user before this date, they will be ignored. Any data received after the deletedUntil date will start building a new user profile.

It might take a couple hours before for the deletion request to be fully processed.

The X-Algolia-API-KEY must contain an API key with the recommendation ACL.

Parameters:

Errors:

• 401: Unauthorized
• 404: Not Found
• 500: Internal Error

1
2
3
4
curl -X DELETE \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://recommendation.us.algolia.com/1/profiles/user_1"

When the query is successful, the HTTP response is a 200 OK and returns the date until which you can safely consider the data as being deleted:

1
2
3
4
{
  "userToken": "user_1",
  "deletedUntil": "2019-09-30T14:01:12Z"
}

Path: /1/strategies/personalization
HTTP Verb: GET

Description:

Get the current personalization strategy.

The strategy contains information on the events and facets that impact user profiles and personalized search results.

The X-Algolia-API-KEY must contain an API key with the recommendation ACL.

Parameters:

1
2
3
4
5
{
  "eventName": "purchase",
  "eventType": "conversion",
  "score": 100
}

1
2
3
4
{
  "facetName": "brand",
  "score": 100
}

Errors:

• 401: Unauthorized
• 404: Not Found
• 500: Internal Error

1
2
3
4
curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://recommendation.us.algolia.com/1/strategies/personalization"

A successful query return a 200 OK HTTP response with the following payload:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
  {
      "eventsScoring": {
          {
              "eventName": "Add to cart",
              "eventType": "conversion",
              "score": 50
          },
          {
              "eventName": "Purchase",
              "eventType": "conversion",
              "score": 100
          }
      },
      "facetsScoring": {
          {
              "facetName": "brand",
              "score": 100
          },
          {
              "facetName": "categories",
              "score": 10
          }
      },
      "personalizationImpact": 75
  }

Path: /1/strategies/personalization
HTTP Verb: POST

Description:

Set a new personalization strategy.

A strategy defines the events and facets that impact user profiles and personalized search results.

The X-Algolia-API-KEY must contain an API key with the recommendation ACL.

Parameters:

1
2
3
4
5
6
7
[
  {
    "eventName": string // mandatory
    "eventType": string // mandatory
    "score": int // mandatory
  }
]

1
2
3
4
5
6
  [
    {
      "facetName": string // mandatory
      "score": int // mandatory
    }
  ]

Errors:

• 401: Unauthorized
• 422: Unprocessable Entity
• 500: Internal Error

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
curl -X POST \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://recommendation.us.algolia.com/1/strategies/personalization"
      -H "Content-Type: application/json" \
      -d '{
            "eventsScoring": [
              {
                "eventName": "Add to cart",
                "eventType": "conversion",
                "score": 50
              },
              {
                "eventName": "Purchase",
                "eventType": "conversion",
                "score": 100
              }
            ],
            "facetsScoring": [
              {
                "facetName": "brand",
                "score": 100
              },
              {
                "facetName": "categories",
                "score": 10
              }
            ]
          }'

A successful query return a 200 OK HTTP response with the following payload:

1
2
3
4
  {
      "status": 200,
      "message": "Strategy was successfully updated"
  }