Contextualize REST API: User and Query Context

Method description

Returns the user context information (top product attributes and the last visited products) and the query context (top product attributes and the top specific products) for a specific user, session and query. While the "userPreferences" and "sessionPreferences" are query agnostic, "userLastViewedProducts"and "sessionLastViewedProducts" and the "queryContext" information are returned for the specific requested query.

With segmentation can sent a user attributes list ("key":"value", ...) and number of tries in the request and the API try to return a segment data using this user attributes. If not have results for this user attributes in this number of tries it return the basic query context. This feature don't have influence in the user context.

The product attribute preferences are calculated based on user clicks, add-to-carts and purchases and the values are normalized using a linear function.

"userPreferences", "sessionPreferences" and "topAttributes" objects don't have a fixed order and it may change in between requests. Although, "values" are sorted by "weight" in descending order.

"userLastViewedProducts" and "sessionLastViewedProducts" weight is calculated using the different between the last time there was an interaction with the product and "now". So, the more recent events will have more weight than others that happened long ago. 

"topProducts" are sorted by "weight" in descending order.

Remember that your EB Contextualize configuration could use different fields for the preferences and topAttributes calculations, so the ones showing below ("brand" and "gender") are just examples.

HTTP method

GET

URL schema

/v2/all/{client_id}?user={user_id}&session={session_id}&query={query}&lang={lang}&preferences.rows={preferences.rows}&last_products.rows={last_products.rows}&session.preferences.rows={session.preferences.rows}&session.last_products.rows={session.last_products.rows}&attributes.rows={attributes.rows}&products.rows={products.rows}&userAttributes={userAttributes}&maxTries={maxTries}&events.min={eventsMin}

URL example

/v2/all/ebdemo?user=id_1234&session=id_5678&query=dress&lang=en&preferences.rows=1&last_products.rows=2&session.preferences.rows=3&session.last_products.rows=3&attributes.rows=3&products.rows=2&userAttributes=gender:male,size:M&maxTries=3&events.min=25


Path Parameters

Parameter nameRequiredDescription
client_id(tick)Client identifier on the system

URI Parameters

Parameter nameRequiredDescriptionDefault
user(tick)Identifier that represents an unique user along the client
session (error) Identifier that represents an unique session for the given user along the client
If it's not specified there isn't session object in response

query

(tick)

Search term that user did
lang(tick)Language of the query
preferences.rows(error) Number of values of each field1
last_products.rows(error) Number of products to return5
session.preferences.rows(error)Number of session values of each field1
session.last_products.rows(error)Number of session products to return5
attributes.rows(error) Number of values of each field1
products.rows(error) Number of products to return5

events.min

 (error) 

Minimum number of events required to return a field or product.

client configuration / 10
userAttributes   (error)User attributes to get segmentation data-
maxTries(error)Max tries to do segmentation intentsclient configuration / 3

Responses

200 - successful request

Type: application/json

Example application/json
{
  "userContext": {
    "userPreferences": [
      {
        "field": "brand",
        "values": [
          {"value": "apple", "weight": 3},
          {"value": "sony", "weight": 2.1}
        ]
      },
      {
        "field": "gender",
        "values": [
          {"value": "woman", "weight": 3}
        ]
      }
    ],
    "sessionPreferences": [
      {
        "field": "brand",
        "values": [
          {"value": "apple", "weight": 3}
        ]
      },
      {
        "field": "gender",
        "values": [
          {"value": "woman", "weight": 3}
        ]
      }
    ],
    "userLastViewedProducts": [
      {"value":"213115", weight:"3"},
      {"value":"213149", weight:"1.3"}
    ],
    "sessionLastViewedProducts": [
      {"value":"213142", weight:"3"}
    ]
  },
  "queryContext": {
    "topAttributes": [
      {
        "field": "brand",
        "values": [
          {"value": "apple", "weight": 3},
          {"value": "sony", "weight": 1.8}
        ]
      },
      {
        "field": "category",
        "values": [
          {"value": "mobiles", "weight": 3}
        ]
      }
    ],
    "topProducts": [
      {"value":"213115", weight:"3"},
      {"value":"213149", weight:"1.3"}
    ]
  }
}
400 - mandatory query parameter is missing

Type: application/json

Example application/json
{
  "code": 400,
  "error": "XXX is mandatory"
}
404 - either client or endpoint don't exist

Type: application/json

Example application/json
{
  "code": 404,
  "error": "XXX not found"
}