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

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, 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

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
  }
}

Example of call:

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...

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):

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 CADP

It is possible to request the API using your own visitor referential:

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

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.

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

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:

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 CADP (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

200

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.

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

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, ...)