# Sending queries to the Recommendations API ## What is a Widget? A XO widget is a recommendation area on your customers' journey used to personalise your visitors' experiences. When requesting recommendations to XO, it's mandatory to provide the Widget ID of your recommendation area.

Widget IDs can be found in the Widgets list of your XO Console

## Personalised recommendation ## Recommendation API `GET` `https://api.early-birds.io/widget/:widgetId/recommendations/:profileId/:variables` Get recommendations for a given user on a given recommendation area. #### Path Parameters | Name | Type | Description | | --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | variables | object | Variables are used to provide the Visitor's context when getting a recommendation | | profileId | string |

Visitor's

profileId

. When using XO Recommendations API with Attraqt Activity pipeline,

profileId

should be

sessionid/:attraqtsessionid

instead of

:profileId

| | widgetId | string | ID of the recommendation area | #### Query Parameters | Name | Type | Description | | ------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | skipAb | boolean | ignore A/B test: will force recommendation display despite the user A/B test population | | store | string | Request items from a specific store | | limit | number | Number of recommendations to be returned | | page | number | Number of the page to be returned (limit \* (page - 1) = offset) | | offset | number |

Result number of the first recommendation to return (

can't be used with page parameter

)

| | fields | string |

Optional but recommended: It allows you to filter the API calls response so it only returns the information you need. This improves the response time reducing the API response size, specifically when the items contain lots of information.

\

Usage example:

fields=recommendations.id

to only recover the products IDs

\

More details about possible usages here:

| | idsToBan | array | List of item IDs to exclude from the recommendation | | nocache | boolean |

Disable the cache

\

⚠️

Don't use it in a production environment because response time will drastically increase.

| | ingoreDisplayRules | boolean | Force recommendations to be displayed with the default rule (ignore restriction rules) | | distribIndexes | number | Return only recommendations for the selected distribution | | locale | string |

Override item attributes with values of a specific localization. Example:

locale=FR

| | metadata | string | Display debug information. You just need to pass some metadata type, separated with a coma. See below for more information. | {% tabs %} {% tab title="200 " %} ``` { "id": "f7c63760-04e4-11ec-9512-a1ffa08cee62", "recommendations": [ { "id": "168", "strategy": "basic-mostPopular", "score": 10, "distribution": 0, "product": { "version": 0, "context": "default", "id": "168", "_id": { "original_id": "168", "tenant": "tenantId", "kind": "product" }, "type": "physical", "title": "RONHILL TECH REVIVE RACER SHORTS - SS21", "url": "", "recommended": true, "booster": 0, "price": 0, "discount_rate": 0, "metadata": { "updated": "1627293494427" }, "categories": [ "BRAND_ronhill", "COLOR_racingred-briwhite", "GENDER_mens", "SPORT_running", "TYPE_shorts" ], "photo": "https://cdn11.bigcommerce.com/s-pv1wa8pmo1/products/168/images/432/RON3364_1000_1__60313__86323.1625826863.386.513.jpg?c=1", "is_price_hidden": 0, "warranty": "", "inventory_warning_level": 0, "height": 0, "brand_name": "RonHill", "cost_price_GBP": 0, "map_prices_GBP": 0, "open_graph_use_meta_description": 1, "mpn": "", "base_variant_id": "0", "preorder_message": "", "option_set_display": "right", "brand_image_url": "", "brand_custom_url": "/ronhill/", "search_keywords": "", "gtin": "", "meta_description": "", "is_condition_shown": 0, "custom_url": "/ronhill-tech-revive-racer-shorts-ss21/", "open_graph_description": "", "sku": "ron3364", "is_preorder_only": 0, "Brand": "RonHill", } }, { "id": "146", "strategy": "basic-mostPopular", "score": 9.960938334216266, "distribution": 0, "product": { "version": 0, "context": "default", "id": "146", "_id": { "original_id": "146", "tenant": "tenantId", "kind": "product" }, "type": "physical", "title": "OMM Kamleika Running Jacket", "url": "", "recommended": true, "booster": 0, "price": 0, "discount_rate": 0, "metadata": { "updated": "1627293494412" }, "categories": [ "BRAND_omm", "COLOR_black", "GENDER_mens", "SPORT_running", "TYPE_trail" ], "photo": "https://cdn11.bigcommerce.com/s-pv1wa8pmo1/products/146/images/410/OMM202_1000_1__41292__87669.1625826850.386.513.jpg?c=1", "is_price_hidden": 0, "warranty": "", "inventory_warning_level": 0, "height": 0, "brand_name": "OMM", "cost_price_GBP": 0, "map_prices_GBP": 0, "open_graph_use_meta_description": 1, "mpn": "", "base_variant_id": "0", "preorder_message": "", "option_set_display": "right", "brand_image_url": "", "brand_custom_url": "/omm/", "search_keywords": "", "gtin": "", "meta_description": "", "is_condition_shown": 0, "custom_url": "/omm-kamleika-running-jacket/", "open_graph_description": "", "sku": "omm202", "is_preorder_only": 0, "Brand": "OMM", } }, { "id": "145", "strategy": "basic-mostPopular", "score": 9.535014093127474, "distribution": 0, "product": { "version": 0, "context": "default", "id": "145", "_id": { "original_id": "145", "tenant": "tenantId", "kind": "product" }, "type": "physical", "title": "Ronhill Tech GORE-TEX ShakeDry Jacket - SS21", "url": "", "recommended": true, "booster": 0, "price": 0, "discount_rate": 0, "metadata": { "updated": "1627293494399" }, "categories": [ "BRAND_ronhill", "COLOR_black", "GENDER_mens", "SPORT_running", "TYPE_jackets" ], "photo": "https://cdn11.bigcommerce.com/s-pv1wa8pmo1/products/145/images/409/RON3191_1000_1__26277__67822.1625826849.386.513.jpg?c=1", "is_price_hidden": 0, "warranty": "", "inventory_warning_level": 0, "height": 0, "brand_name": "RonHill", "cost_price_GBP": 0, "map_prices_GBP": 0, "open_graph_use_meta_description": 1, "mpn": "", "base_variant_id": "0", "preorder_message": "", "option_set_display": "right", "brand_image_url": "", "brand_custom_url": "/ronhill/", "search_keywords": "", "gtin": "", "meta_description": "", "is_condition_shown": 0, "custom_url": "/ronhill-tech-gore-tex-shakedry-jacket-ss21/", "open_graph_description": "", "sku": "ron3191", "is_preorder_only": 0, "Brand": "RonHill", } }, { "id": "226", "strategy": "basic-mostPopular", "score": 9.465919230788467, "distribution": 0, "product": { "version": 0, "context": "default", "id": "226", "_id": { "original_id": "226", "tenant": "tenantId", "kind": "product" }, "type": "physical", "title": "Adidas Own The Run Women's T-Shirt - AW21", "url": "", "recommended": true, "booster": 0, "price": 0, "discount_rate": 0, "metadata": { "updated": "1627293494381" }, "categories": [ "BRAND_adidas", "COLOR_black", "GENDER_womens", "SPORT_running-gym", "TYPE_t-shirts" ], "photo": "https://cdn11.bigcommerce.com/s-pv1wa8pmo1/products/226/images/495/ADI14503_1000_1__71261.1626887677.386.513.jpg?c=1", "is_price_hidden": 0, "warranty": "", "inventory_warning_level": 0, "height": 0, "brand_name": "Adidas", "cost_price_GBP": 0, "map_prices_GBP": 0, "open_graph_use_meta_description": 1, "mpn": "", "base_variant_id": "0", "preorder_message": "", "option_set_display": "right", "brand_image_url": "", "brand_custom_url": "/adidas/", "search_keywords": "", "gtin": "", "meta_description": "", "is_condition_shown": 0, "custom_url": "/adidas-own-the-run-womens-t-shirt-aw21/", "open_graph_description": "", "sku": "adi14503", "is_preorder_only": 0, "Brand": "Adidas", } } ], "pagination": { "total": 4 }, "widget": { "title": "Most Popular", "attributes": {}, "minResults": -1 } } ``` {% endtab %} {% endtabs %} *Example of call:* ```bash curl "http://api.early-birds.io/widget/{{widgetId}}/recommendations/{{profileId}}? variables={ '$productId': {{productId}}, '$category': {{category}} }" -X GET -H "Content-Type: application/json" ``` Available `metadata` options : | Metadata | Description | | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | time | Total time took to generate the recommendation | | count | Number of items recommended | | idsToBan | Products removed from the recommendation | | skipByAbTestGeneral | true if the user is in a population that can't see any widget, because a global AB test is in progress. If true, recommendations will be an empty array. | | skipByAbTestGeneralWidget | true if the user is in a population that can't see this particular widget, because an AB test is activated for this widget. If true, recommendations will be an empty array. | | skipByDisplayRules | true if this widget doesn't match the rules configured in the dashboard. | | skipBy | string value that explains why no recommendation is returned. It can be equal to "abTestGeneral", "abTestGeneralWidget", "widgetDisabled" or "widgetDisabledByDisplayRules" | | nbFiniteRecos | Number of items recommended before the infinite distribution is triggered. | | variables | All variables available for this widget, and their values. | | items | List of returned item ids and their scores. | | nbRecos | Number of items recommended (alias of count). | | nbRecosByStrategy | Number of items recommended for each strategy. | | widgetId | Widget id | | abWidgetId | Id of the running AB test for this widget (null if there is no AB test running). This is for AB test between different merchandising rules, placements, templates or titles. | | abGeneralWidgetId | Id of the running general AB test for this widget (null if there is no AB test running). This is for with/without AB test. | | profile | Detailed user profile. It contains information such as AB test populations, datasources, infos, segments, last activities. | {% hint style="info" %} *Adding the `variables` query parameter is provided as an example. Even if you are not requesting the API with a `profileId`, adding the context in which you want to get a recommendation is still a good practice.* {% endhint %} ### Recommendation for a specific user - When using the Activity API If you use the Activity API and identity Repository, when your user is identified through an identifier (for example after user login), you must use this identifier to request recommendations. *See* [https://github.com/Attraqt/product-discovery-documentation/blob/main/new-docs/Displaying-Results/XO-Front-End/broken-reference/README.md](https://github.com/Attraqt/product-discovery-documentation/blob/main/new-docs/Displaying-Results/XO-Front-End/broken-reference/README.md "mention") *to learn more about Identities.* **UserID (or any loggedin id):** ```bash curl "https://api.early-birds.io/widget/{{widgetId}}/recommendations/{{identityRepository}}/{{userId}}/" -X GET -H "Content-Type: application/json" ``` Where: * `{{widgetId}}` with the widget ID that you would like to display * `{{identityRepository}}` with the identity repository that you are using * `{{userId}}` is the id of the identified user ### Recommendation for a specific user - When not using the Activity API It is possible to request the API using your own visitor referential: ```bash curl "http://api.early-birds.io/widget/{{widgetId}}/recommendations/{{datasourceId}}/{{userId}}" -X GET -H "Content-Type: application/json" ``` Where: * `{{widgetId}}` with the widget ID that you would like to display * `{{datasourceId}}` with the datasource ID (ID of your own visitor referential) * `{{userId}}` with the visitor ID in your own referential {% hint style="info" %} *Adding the `variables` query parameter is provided as an example. Even if you are not requesting the API with a `profileId`, adding the context in which you want to get a recommendation is still a good practice.* {% endhint %} ## Anonymous recommendation For many reasons, you might need to request the Recommendation API without providing a `profileId`. It can be done by calling our API without providing a `profileId`. ```bash curl "http://api.early-birds.io/widget/{{widgetId}}/recommendations? variables={ '$productId': {{productId}}, '$category': {{category}} }" -X GET -H "Content-Type: application/json" ``` Where: * `{{widgetId}}` with the widget ID that you would like to display * `{{productId}}` Product ID if you are on the product page * `{{category}}` Category users are currently viewing {% hint style="info" %} *Adding the `variables` query parameter is provided as an example. Even if you are not requesting the API with a `profileId`, adding the context in which you want to get a recommendation is still a good practice.* {% endhint %} ## Requesting multiple recommendation area at the same time To retrieve results for multiple recommendation areas, you can use the following endpoint: ## Multiple widgets `GET` `https://api.early-birds.io/widget/multi/:widgetIds/recommendations/:profileId` To retrieve results for multiple recommendation areas, you can use this endpoint. The **only** difference with the Recommendation API is the `widgetIds` . \\ \\ ⚠️ Does not work with the Activity API (sessionId) #### Path Parameters | Name | Type | Description | | --------- | ------ | ---------------------------------------------------------------------------------------- | | profileId | string | Visitor's profile id | | | string | List of widget IDs that you would like to get recommendations for, separated with a dash | {% tabs %} {% tab title="200 " %} ``` ``` {% endtab %} {% endtabs %} ## Emails recommendation Following API calls have been created to generate a recommendation directly through email HTML code. Each call will return a unique item recommendation. If email is implemented through API, or through a CSV file exchange, it’s not recommended to use the following calls. The widget API calls described earlier can be used to retrieve all the items recommended through a single API call. ### Image generation for a user ID This API endpoint will return the generated image for the recommended item. Usually, this method is used directly in an HTML tag and is not called as a standard API endpoint. You can switch to “Tags” in the right column to see how it works. ```bash curl "http://api.early-birds.io/widget/{{widgetId}}/recommendations/{{datasourceId}}/{{userId}}/{{index}}/photo.png" -X GET ``` Where: * `{{widgetId}}` with the widget ID that you would like to display * `{{datasourceId}}` with the datasource ID (ID of your own visitor referential) * `{{userId}}` with the visitor ID in your own referential * `{{index}}` item position (example: 1, 2, 3, ...) ### Link generation for a user ID ```bash curl "http://api.early-birds.io/widget/{{widgetId}}/recommendations/{{datasourceId}}/{{userId}}/{{index}}/redirect.html" -X GET ``` Where: * `{{widgetId}}` with the widget ID that you would like to display * `{{datasourceId}}` with the datasource ID (ID of your own visitor referential) * `{{userId}}` with the visitor ID in your own referential * `{{index}}` item position (example: 1, 2, 3, ...) --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://crownpeak.gitbook.io/product-discovery/building-the-front-end-experience-with-xo/using-the-recommendations-api.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.