GET /{environment}/recommendations/lists

Description

Query cached items in a list computed in an environment-aware setup.

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.

string

Query

offset
required

The rank of the first item to be requested. Starts at counting at 1.

integer

Responses

HTTP Code Description Schema

200

OK

Recommendations

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" : [ {
    "configuration_id" : "some_id",
    "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",
  "version" : "froomle_1"
}

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 your Froomle Solution Architect to set this up.

string

item_id
required

The identifier of the recommended item

string

rank
required

The rank at which the item is recommended. Starts counting at 1.

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

configuration_id
optional

Bytestring identifier of the List’s configuration.

string

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

Recommendations

Name Description Schema

device_id
optional

Unique identifier for an unregistered user (e.g. cookie)

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 given for the request

string

version
optional

The A/B version the user is currently assigned to.

string