Attraqt
Search…
Using the Recommendations API
Our Recommendations API is used to personalised the Shopping experiences of your visitors.

What is a Widget?

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.
Widget IDs can be found in the Widgets list of your XO Console

Personalised Recommendation

get
https://api.early-birds.io/widget/:widgetId/recommendations/:profileId/:variables
Recommendation API
Example of call:
1
curl "http://api.early-birds.io/widget/{{widgetId}}/recommendations/{{profileId}}?
2
variables={
3
'$productId': {{productId}},
4
'$category': {{category}}
5
}"
6
-X GET
7
-H "Content-Type: application/json"
Copied!
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...
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.

Recommendation for a specific User - When using CADP

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 Managing identities to learn more about Identities.
UserID (or any loggedin id):
1
curl "https://api.early-birds.io/widget/{{widgetId}}/recommendations/{{identityRepository}}/{{userId}}/"
2
-X GET
3
-H "Content-Type: application/json"
Copied!
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 CADP

It is possible to request the API using your own visitor referential:
1
curl "http://api.early-birds.io/widget/{{widgetId}}/recommendations/{{datasourceId}}/{{userId}}"
2
-X GET
3
-H "Content-Type: application/json"
Copied!
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.

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.
1
curl "http://api.early-birds.io/widget/{{widgetId}}/recommendations?
2
variables={
3
'$productId': {{productId}},
4
'$category': {{category}}
5
}"
6
-X GET
7
-H "Content-Type: application/json"
Copied!
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.

Requesting multiple recommendation Area at the same time

To retrieve results for multiple recommendation areas, you can use the following endpoint:
get
https://api.early-birds.io/widget/multi/:widgetIds/recommendations/:profileId
Multiple widgets

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.
1
curl "http://api.early-birds.io/widget/{{widgetId}}/recommendations/{{datasourceId}}/{{userId}}/{{index}}/photo.png"
2
-X GET
Copied!
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, ...)
1
curl "http://api.early-birds.io/widget/{{widgetId}}/recommendations/{{datasourceId}}/{{userId}}/{{index}}/redirect.html"
2
-X GET
Copied!
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, ...)
Last modified 13d ago