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 RecommendationRequest Responses HTTP Code Description Schema 200 OK 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 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 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" : [ { "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 Histories 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