Recommendations API

Getting recommendations from the Froomle platform is done through the recommendations API. The recommendations in the API will only contain items which are stored in the specified environment. In addition to requesting recommendations, the recommendations API also supports fetching previously computed recommendations.

Specifications

POST /{environment}/recommendations/requests

Description

Request newly computed recommendations.

Parameters

Type Name Description Schema

Path

environment
required

The environment for which the request is made.

string

Body

body
required

Responses

HTTP Code Description Schema

200

OK

400

The recommendation body was not in the right format, was missing mandatory information or one of the fields (channel, page_type, list_name etc.) has an invalid value.

No Content

Consumes

  • application/json

Produces

  • application/json

Example HTTP request

Request body
{
  "channel" : "www-desktop",
  "device_id" : "the-cookie-id-123",
  "histories" : {
    "pageviews" : [ {
      "id" : "electronics",
      "item_type" : "article",
      "timestamp" : 1581076041
    }, {
      "id" : "beauty",
      "item_type" : "article",
      "timestamp" : 1581054230
    }, {
      "id" : "gaming",
      "item_type" : "article",
      "timestamp" : 1581054230
    } ]
  },
  "lists" : [ {
    "limit" : 5,
    "list_name" : "Some list name",
    "list_size" : 10
  } ],
  "page_type" : "home",
  "user_id" : "the-user-id-123-like-cookie"
}

Example HTTP response

Response 200
{
  "device_id" : "the-cookie-id-123",
  "lists" : [ {
    "items" : [ {
      "information_field" : "some_metadata",
      "item_id" : "item_id_1",
      "rank" : 1
    }, {
      "information_field" : "some_metadata",
      "item_id" : "item_id_2",
      "rank" : 2
    } ],
    "limit" : 2,
    "list_key" : "a_unique_list_identifier",
    "list_name" : "Some list name",
    "list_size" : 10
  } ],
  "request_id" : "2141141",
  "user_group" : "froomle",
  "user_id" : "the-user-id-123-like-cookie",
}

cURL Example

$ curl --location --request POST 'https://{subdomain}.froomle.com/api/{environment}/recommendations/requests' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer X' \
--data-raw '{
    "page_type": "article_page",
    "channel": "www-mobile",
    "device_id": "client_user_id_001",
    "context_item": "113437",
    "context_item_type": "product",
    "lists": [
        {
            "list_name": "reco_list_001",
            "list_size": 5,
            "limit": 2
        }
    ]
}'

GET /{environment}/recommendations/lists

Description

Request previously computed recommendations. These are stored per list and can be queried using the list_key present in the original recommendation response. The cache containing these recommendations has a limited lifetime. Common use case for the list endpoints is a carousel where only part of the recommendations are shown initially. Then for the initial set of recommendations a regular request is made while for the next elements the lists endpoint is used.

💡 Note that this functionality requires an additional cache and is disabled by default. Contact support to activate it on your integration.

Parameters

Type Name Description Schema

Path

environment
required

The environment for which a request is made.

string

Query

limit
required

The number of items to fetch.

integer

Query

list_key
required

String identifier of the previously computed list to request recommended items from. This can be retrieved from the response body of the initial recommendations request.

string

Query

offset
required

The rank of the first item to be requested. Starts counting at 1. In case the initial carousel contained 7 recommendations, this value would be 8 for the subsequent request.

integer

Responses

HTTP Code Description Schema

200

OK

404

list_key not found, it either expired or never existed

No Content

Produces

  • application/json

Tags

  • recommendations

Example HTTP response

Response 200
{
  "device_id" : "the-cookie-id-123",
  "lists" : [ {
    "items" : [ {
      "information_field" : "some_metadata",
      "item_id" : "item_id_1",
      "rank" : 1
    }, {
      "information_field" : "some_metadata",
      "item_id" : "item_id_2",
      "rank" : 2
    } ],
    "limit" : 2,
    "list_key" : "a_unique_list_identifier",
    "list_name" : "Some list name",
    "list_size" : 10
  } ],
  "request_id" : "2141141",
  "user_group" : "froomle",
  "user_id" : "the-user-id-123-like-cookie"
}

cURL Example

$ curl --location --request GET 'https://{subdomain}.froomle.com/api/{environment}/recommendations/lists?offset=1&limit=3&list_key={list_key}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer X'

Definitions

HistoryItem

Single event entity defined by at least an identifier

Name Description Schema

id
required

Identifier of the entity of the event, we support most entities that would appear in a detail_pageview or item_interaction.

string

item_type
optional

Type of the entity (e.g. item, article, video, category, group, …). These types are Froomle-defined, please consult your solutions architect for the correct type.

string

reconsumable
optional

True if the entity is allowed to appear in the generated recommendations

boolean

timestamp
optional

Unix timestamp (seconds since Jan 1st 1970 00:00:00) of the event

integer


Histories

Dict of additional customer-defined histories each having a maximum length of 50 tuples

Type : < string, < HistoryItem > array > map


Item

One content-item.

Name Description Schema

information_field
optional

The Froomle API can be configured to return additional information fields (if present in the item information). Please contact the Froomle support team to set this up.

string

item_id
required

The identifier of the recommended item

string

rank
required

The rank at which the item should be recommended. Starts counting at 1. If not specified, Froomle will decide the rank.

integer


List

A list of limit items is returned. Potentially the list consists of list_size items in total, of which the next can be queried by passing the list_key to the /lists endpoint.

Name Description Schema

items
optional

List of limit Items. limit is equal to the minimum of limit specified in the request and the number of recommendations found.

< Item > array

limit
optional

Number of Items returned

integer

list_key
optional

Bytestring identifier of the List.

string

list_name
optional

Bytestring name of the list. As specified in the request.

string

list_size
optional

Total number of Items in this List (of which only limit Items are returned)

integer


ListContentItem

One mandatory list-content-item.

Name Description Schema

id
required

The identifier of the mandatory item.

string

item_type
optional

Type of the entity (e.g. item, article, video, category, group, …). These types are Froomle-defined, please consult your solutions architect for the correct type.

string

rank
optional

The rank at which the item should be recommended. Starts counting at 1. If not specified, Froomle will decide the rank.

integer


RecommendationRequest

Specification of a Recommendation request.

Name Description Schema

channel
required

The channel used to request the recommendations. Accepted channels are: www, www-desktop, www-mobile, app, app-ios, app-android, app-audio, app-audio-ios and app-audio-android. If none of these fit your use case, please get in touch with your account manager.

string

context_item
optional

Unique identifier for the currently displayed item. Required only on article pages.

string

context_item_type
optional

Type of the currently displayed item, if applicable.

string

device_id
required

Unique identifier for a unregistered user (e.g. cookie). Use the value "no-consent" for users that wish to remain anonymous.

string

histories
optional

lists
required

< RequestList > array

page_type
required

The page type to request recommendations for. Accepted page_types are: home, article, category, foryou, regional and promotion. If none of these fit your use case, please get in touch with your account manager.

string

user_id
optional

Unique identifier for a logged-in user

string


Recommendations

Name Description Schema

device_id
optional

Unique identifier for an unregistered user (e.g. cookie). Use the value "no-consent" for users that wish to remain anonymous.

string

lists
optional

List of lists of items

< ResponseList > array

request_id
optional

The request identifier as supplied by Froomle. This request_id needs to be supplied with each logged event.

string

user_group
optional

The group the user is assigned to. If users get the Froomle experience, this will always be "froomle".

string

user_id
optional

the user id of the logged-in user

string


RequestList

The specification to configure which lists of items to retrieve.

Name Description Schema

limit
optional

default = list_size

integer

list_content
optional

A list of items (id, item_type, rank) that will be injected in the response.

< ListContentItem > array

list_name
required

A string identifier for the list. The list names should be unique in a single request.

string

list_size
required

The number of items to recommend.

integer


ResponseList

A list of limit items is returned. Potentially the list consists of list_size items in total, of which the next can be queried by passing the list_key to the /lists endpoint.

Name Description Schema

items
optional

List of limit Items. limit is equal to the minimum of limit specified in the request and the number of recommendations found.

< Item > array

limit
optional

Number of Items returned

integer

list_key
optional

Bytestring identifier of the List.

string

list_name
optional

Bytestring name of the list. As specified in the request.

string

list_size
optional

Total number of Items in this List (of which only limit Items are returned)

integer