# Recommendations API

> Current Froomle documentation · [View canonical page](https://docs.froomle.com/froomle-doc-main/v2/api_reference/recommendations/index.html)

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

Use the [Recommendation Request Model](https://docs.froomle.com/froomle-doc-main/v2/guide/topics/recommendation-requests.html) for shared request behavior. For implementation, use [Frontend SDK recommendations](https://docs.froomle.com/froomle-doc-main/v2/js_lib/jslib.html#SdkRecommendations) or [Manual Recommendation Integration](https://docs.froomle.com/froomle-doc-main/v2/guide/manual-integration/recommendations.html).

<a id="_specifications"></a>

## Specifications

<a id="_recommendations_api_api_recommendations_get_recommendations"></a>

### POST /{environment}/recommendations/requests

<a id="_description"></a>

#### Description

Request newly computed recommendations. For each list, the response returns up to `limit` items from the start of the ranked list, beginning at rank 1.

<a id="_parameters"></a>

#### Parameters

| Type | Name | Description | Schema |
| --- | --- | --- | --- |
| **Path** | **environment**<br>_required_ | The environment for which the request is made. | string |
| **Body** | **body**<br>_required_ |  | [RecommendationRequest](https://docs.froomle.com/froomle-doc-main/v2/api_reference/recommendations/index.html#_recommendationrequest) |

<a id="_responses"></a>

#### Responses

| HTTP Code | Description | Schema |
| --- | --- | --- |
| **200** | OK | [Recommendations](https://docs.froomle.com/froomle-doc-main/v2/api_reference/recommendations/index.html#_recommendations) |
| **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 |

<a id="_consumes"></a>

#### Consumes

-   `application/json`
    

<a id="_produces"></a>

#### Produces

-   `application/json`
    

<a id="_example_http_request"></a>

#### Example HTTP request

<a id="_request_body"></a>

##### Request body

```json
{
  "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" : 2,
    "list_name" : "reco_list_001",
    "list_size" : 5
  } ],
  "page_type" : "home",
  "user_id" : "customer-user-id-123"
}
```

<a id="_example_http_response"></a>

#### Example HTTP response

<a id="_response_200"></a>

##### Response 200

```json
{
  "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" : "reco_list_001",
    "list_size" : 5
  } ],
  "request_id" : "2141141",
  "user_group" : "froomle",
  "user_id" : "customer-user-id-123"
}
```

<a id="_curl_example"></a>

#### cURL Example

```console
$ 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_detail",
    "channel": "www-mobile",
    "device_id": "the-cookie-id-123",
    "context_item": "113437",
    "context_item_type": "article",
    "lists": [
        {
            "list_name": "reco_list_001",
            "list_size": 5,
            "limit": 2
        }
    ]
}'
```

* * *

<a id="_recommendations_api_api_recommendations_get_precomputed"></a>

### GET /{environment}/recommendations/lists

<a id="_description_2"></a>

#### Description

Retrieve a slice of a previously computed ranked list using the `list_key` from the original recommendation response, including a smart-sorting response. The original request returns the beginning of the list, starting at rank 1. For example, after it returns ranks 1 and 2, request `offset=3&limit=2` to retrieve ranks 3 and 4. The list remains available for a limited time. List-page retrieval must be enabled for your environment; contact Froomle if you need it.

<a id="_parameters_2"></a>

#### Parameters

| Type | Name | Description | Schema |
| --- | --- | --- | --- |
| **Path** | **environment**<br>_required_ | The environment for which a request is made. | string |
| **Query** | **limit**<br>_required_ | Maximum number of items to return, starting at `offset`. | integer |
| **Query** | **list\_key**<br>_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**<br>_required_ | The 1-based rank of the first item to return from the stored list. Use 1 for the first item or 3 for the third item. This is not a page number or the number of items to skip. | integer |

<a id="_responses_2"></a>

#### Responses

| HTTP Code | Description | Schema |
| --- | --- | --- |
| **200** | OK | [Recommendations](https://docs.froomle.com/froomle-doc-main/v2/api_reference/recommendations/index.html#_recommendations) |
| **404** | list\_key not found, it either expired or never existed | No Content |

<a id="_produces_2"></a>

#### Produces

-   `application/json`
    

<a id="_tags"></a>

#### Tags

-   recommendations
    

<a id="_example_http_response_2"></a>

#### Example HTTP response

<a id="_response_200_2"></a>

##### Response 200

```json
{
  "device_id" : "the-cookie-id-123",
  "lists" : [ {
    "items" : [ {
      "item_id" : "item_id_3",
      "rank" : 3
    }, {
      "item_id" : "item_id_4",
      "rank" : 4
    }, {
      "item_id" : "item_id_5",
      "rank" : 5
    } ],
    "limit" : 3,
    "list_key" : "a_unique_list_identifier",
    "list_name" : "reco_list_001",
    "list_size" : 5,
    "offset" : 3
  } ],
  "request_id" : "2141141",
  "user_group" : "froomle",
  "user_id" : "customer-user-id-123"
}
```

<a id="_curl_example_2"></a>

#### cURL Example

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

The POST example requests a ranked list of up to five items and returns the first two, at ranks 1 and 2. Use the `list_key` from that response for subsequent GET requests. The GET above requests up to three items starting at rank 3, so it returns ranks 3 through 5 if all five items are available.

`offset` names the **first rank to return**; `limit` names the **maximum number of items to return**. The endpoint accepts neither a page number nor a count of items to skip. For the same five-item list:

| `offset` | `limit` | Ranks returned |
| --- | --- | --- |
| 1 | 2 | 1, 2 (the beginning of the list again) |
| 3 | 2 | 3, 4 (the next two items after the POST) |
| 5 | 2 | 5 (only one item remains) |
| 4 | 2 | 4, 5 (an arbitrary slice) |

These examples assume that all five requested items are available. The POST has no `offset` parameter; it always starts at rank 1.

* * *

<a id="_definitions"></a>

## Definitions

<a id="_historyitem"></a>

### HistoryItem

Single event entity defined by at least an identifier

| Name | Description | Schema |
| --- | --- | --- |
| **id**<br>_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**<br>_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**<br>_optional_ | True if the entity is allowed to appear in the generated recommendations | boolean |
| **timestamp**<br>_optional_ | Unix timestamp (seconds since Jan 1st 1970 00:00:00) of the event | integer |

* * *

<a id="_histories"></a>

### Histories

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

_Type_ : < string, < [HistoryItem](https://docs.froomle.com/froomle-doc-main/v2/api_reference/recommendations/index.html#_historyitem) > array > map

* * *

<a id="_item"></a>

### Item

One content-item.

| Name | Description | Schema |
| --- | --- | --- |
| **information\_field**<br>_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**<br>_required_ | The identifier of the recommended item | string |
| **rank**<br>_required_ | The item’s position in the complete ranked list. The first item has rank 1. | integer |

* * *

<a id="_listcontentitem"></a>

### ListContentItem

One supplied candidate or fixed-rank item. If used in a request with more than one list, use exclusions as needed to avoid repeats across lists.

| Name | Description | Schema |
| --- | --- | --- |
| **id**<br>_required_ | Identifier of the supplied item. | string |
| **item\_type**<br>_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**<br>_optional_ | The rank at which the item should be recommended. Starts counting at 1. If not specified, Froomle will decide the rank. | integer |

* * *

<a id="_recommendationrequest"></a>

### RecommendationRequest

Specification of a Recommendation request.

| Name | Description | Schema |
| --- | --- | --- |
| **channel**<br>_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**<br>_optional_ | Unique identifier for the currently displayed item. Required only on article pages. | string |
| **context\_item\_type**<br>_optional_ | Type of the currently displayed item, if applicable. | string |
| **device\_id**<br>_required_ | Unique identifier for a unregistered user (e.g. cookie). Use the value `"no-consent"` for users that wish to remain anonymous. | string |
| **histories**<br>_optional_ |  | [Histories](https://docs.froomle.com/froomle-doc-main/v2/api_reference/recommendations/index.html#_histories) |
| **lists**<br>_required_ | One or more lists of recommendations to receive. When showing multiple recommendation blocks (e.g. “recommended for you”, “continue reading”, “recent items”) on the same page, include all of them in a single lists array. This ensures that recommendations are generated together, enabling the engine to avoid duplicate items across blocks. | < [RequestList](https://docs.froomle.com/froomle-doc-main/v2/api_reference/recommendations/index.html#_requestlist) > array |
| **page\_type**<br>_required_ | The page type to request recommendations for. Standard page\_types are: home, category, article\_detail, product\_detail, video\_detail, and checkout. If none of these fit your use case, please get in touch with your account manager. | string |
| **user\_id**<br>_optional_ | Unique identifier for a logged-in user | string |

* * *

<a id="_recommendations"></a>

### Recommendations

| Name | Description | Schema |
| --- | --- | --- |
| **device\_id**<br>_optional_ | Unique identifier for an unregistered user (e.g. cookie). Use the value `"no-consent"` for users that wish to remain anonymous. | string |
| **lists**<br>_optional_ | List of lists of items | < [ResponseList](https://docs.froomle.com/froomle-doc-main/v2/api_reference/recommendations/index.html#_responselist) > array |
| **request\_id**<br>_optional_ | The request identifier as supplied by Froomle. This request\_id needs to be supplied with each logged event. | string |
| **user\_group**<br>_optional_ | The group the user is assigned to. If users get the Froomle experience, this will always be "froomle". | string |
| **user\_id**<br>_optional_ | the user id of the logged-in user | string |

* * *

<a id="_requestlist"></a>

### RequestList

The specification to configure which lists of items to retrieve.

| Name | Description | Schema |
| --- | --- | --- |
| **alias**<br>_optional_ | Optional identifier that distinguishes repeated list names within one request. | string |
| **limit**<br>_optional_ | Maximum number of items to return initially. Defaults to list\_size. | integer |
| **list\_content**<br>_optional_ | Candidate items to rerank, or items pinned to a position when rank is provided. | < [ListContentItem](https://docs.froomle.com/froomle-doc-main/v2/api_reference/recommendations/index.html#_listcontentitem) > array |
| **list\_name**<br>_required_ | A string identifier for the list. Repeated names require a distinct alias for each instance. | string |
| **list\_size**<br>_required_ | Maximum number of items to rank for the complete list. | integer |

* * *

<a id="_responselist"></a>

### ResponseList

Contains up to `limit` items from a ranked list requested with `list_size`. If a `list_key` is available, further pages can be requested from the /lists endpoint.

| Name | Description | Schema |
| --- | --- | --- |
| **items**<br>_optional_ | Items returned for this page, up to the requested `limit`. Fewer items may be returned when fewer eligible recommendations are available. | < [Item](https://docs.froomle.com/froomle-doc-main/v2/api_reference/recommendations/index.html#_item) > array |
| **limit**<br>_optional_ | Maximum number of items requested for this page, not the number actually returned. | integer |
| **list\_key**<br>_optional_ | Opaque identifier used to request further pages, when available. | string |
| **list\_name**<br>_optional_ | Bytestring name of the list. As specified in the request. | string |
| **list\_size**<br>_optional_ | Number of items requested for the complete ranked list. This is not a guaranteed count of eligible items. | integer |
| **offset**<br>_optional_ | 1-based rank of the first item in this page, returned by the /lists endpoint. | integer |