Recommendations API Copy page Copy link View Markdown 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 for shared request behavior. For implementation, use Frontend SDK recommendations or Manual Recommendation Integration. Specifications POST /{environment}/recommendations/requests 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. 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" : 2, "list_name" : "reco_list_001", "list_size" : 5 } ], "page_type" : "home", "user_id" : "customer-user-id-123" } 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" : "reco_list_001", "list_size" : 5 } ], "request_id" : "2141141", "user_group" : "froomle", "user_id" : "customer-user-id-123" } 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_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 } ] }' GET /{environment}/recommendations/lists 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. Parameters Type Name Description Schema Path environment required The environment for which a request is made. string Query limit required Maximum number of items to return, starting at offset. 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 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 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" : [ { "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" } cURL Example $ 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. 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 item’s position in the complete ranked list. The first item has rank 1. integer 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 required Identifier of the supplied 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 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 > array page_type 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 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 alias optional Optional identifier that distinguishes repeated list names within one request. string limit optional Maximum number of items to return initially. Defaults to list_size. integer list_content optional Candidate items to rerank, or items pinned to a position when rank is provided. < ListContentItem > array list_name required A string identifier for the list. Repeated names require a distinct alias for each instance. string list_size required Maximum number of items to rank for the complete list. integer 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 optional Items returned for this page, up to the requested limit. Fewer items may be returned when fewer eligible recommendations are available. < Item > array limit optional Maximum number of items requested for this page, not the number actually returned. integer list_key optional Opaque identifier used to request further pages, when available. string list_name optional Bytestring name of the list. As specified in the request. string list_size optional Number of items requested for the complete ranked list. This is not a guaranteed count of eligible items. integer offset optional 1-based rank of the first item in this page, returned by the /lists endpoint. integer