Using the Recommendations API
Our Recommendations API is used to personalised the Shopping experiences of your visitors.
Last updated
Product Discovery Developer Guide
Our Recommendations API is used to personalised the Shopping experiences of your visitors.
Last updated
A XO Widget is a recommendation Area on your customers' journey that is used to personalise your visitors' experiences. When requesting recommendations to XO, it's mandatory to provide the Widget ID of your recommendation Area.
GET https://api.early-birds.io/widget/:widgetId/recommendations/:profileId/:variables
Get recommendations for a given user on a given recommendation Area
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
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, specially when the items contain lots of information.
\
Usage example:
fields=recommendations.id
to only recover the products IDs
\
More details about possible usages here: https://github.com/nemtsov/json-mask
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
Example of call:
Available metadata options :
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...
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.
If you use CADP 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 to learn more about Identities.
UserID (or any loggedin id):
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
It is possible to request the API using your own visitor referential:
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
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.
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.
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
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.
To retrieve results for multiple recommendation areas, you can use the following endpoint:
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 CADP (sessionId)
profileId
string
Visitor's profile id
string
List of widget IDs that you would like to get recommendations for, separated with a dash
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.
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.
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, ...)
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, ...)
