API Reference / REST API / Recommendation API
Oct. 03, 2019

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:

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 admin API key for 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

Verb Path Method

GET

/1/profiles/personalization/{userToken}

Get a usertoken profile

DELETE

/1/profiles/personalization/{userToken}

Delete a user profile

Get a usertoken profile

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

userToken
type: string
Required

userToken representing the user for which to fetch the Personalization profile.

Errors:

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

Example:

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

Delete a user profile

Path: /1/profiles/personalization/{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:

userToken
type: string
Required

The userToken representing the user for which to delete the Personalization profile and associated data.

Errors:

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

Example:

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

Did you find this page helpful?