Personalization API

The Personalization 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 (named recommendation for legacy reasons, subject to change) and the response format.

Domain

The Personalization 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://personalization.us.algolia.com
• Europe: https://personalization.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 Personalization 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.

User profile endpoints

Quick reference

Path: /1/profiles/personalization/{userToken}
HTTP Verb: GET
Required API Key: any key with the recommendation ACL

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.

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://personalization.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
Required API Key: any key with the recommendation ACL

Description:

Delete the user profile and its associated data.

The response includes a deleteUntil attribute. This timestamp indicates until when the user data can be safely considered deleted. Events sent before this time are ignored, while events sent after this time create a new user profile.

To delete all click and conversion events associated with a userToken, see Delete a user token

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

Strategy endpoints

Quick reference

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
6
7
[
  {
    "eventName": "purchase",
    "eventType": "conversion",
    "score": 100
  }
]

1
2
3
4
5
6
[
  {
    "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://personalization.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
30
curl -X POST \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://personalization.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
              }
            ],
            "personalizationImpact": 100
          }'

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

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