Articles in this section

Using HTTP to rank items using the Relevance Engine

Below is an example of how to perform a relevance ranking request using the curl command line utility:

curl 'https://convert-relevance-avatria-shared01-use2.avatria.cloud/infer/rank' 
  -H 'content-type: application/json' 
  -H 'accept: */*' 
  -d '{"campaignId":"6a63dc88-23fd-4dc3-96e7-bcb7fd39fdda","query":{"id":"/c/books/literature-and-fiction/literary"},"items":[{"id":"B00LPLHQ3W"},{"id":"B009Q0VAOK"},{"id":"B009VGRFKM"},{"id":"B009W7HD16"}]}'

Below is a formatted version of the JSON payload for this example.

{
   "campaignId":"6a63dc88-23fd-4dc3-96e7-bcb7fd39fdda",
   "user":{
      "id:"convert.demo@avatria.com"
   },
   "query":{
      "id":"/c/books/literature-and-fiction/literary"
   },
   "items":[
      {
         "id":"B00LPLHQ3W"
      },
      {
         "id":"B009Q0VAOK"
      },
      {
         "id":"B009VGRFKM"
      },
      {
         "id":"B009W7HD16"
      }
   ]
}

Below we explore the request parameters.

  • campaignId (required)
    • The ID associated with the Relevance Campaign which has been setup for this example. In this case, we are using the ID associated with the 'Purchase Optimization' campaign for the Nile Books Demo account. has been created for this example.
    • For this request to succeed, the campaign must be Active and associated with a successfully generated Solution Version.
  • query.id (optional)
    • An ID representing the query being performed by the user (search results page, product listing page, PDP page, etc).
    • The query section may be omitted if the query is for an ad-hoc list of items. This is sometimes called a global query and will typically be handled using a model tuned for optimized global (e.g. 'All Products') type requests.
    • If using Google Analytics as a analytics provider, the query ID value should be the same value as is being used to track views and clicks to the 'listName' dimension.
  • user.id (optional)
    • An ID representing the user which the request is associated.
    • The user section may be omitted if the personalization features are not enabled on the model or if the user is not authenticated. 
    • Used to to personalized results. If no ID is provided, the items in the request will be treated as anonymous but will still be optimized based upon other input factors (e.g. historical conversion activity for the given query, device type, location). 
    • If using Google Analytics as a analytics provider, the user ID value should be the same value as used to track activity to a user in Google Analytics. By default, the Google Analytics client ID is used as the default identifier for users. User scoped custom dimensions can also be used to track user activity to a more useful identifier value. Please work with the Avatria Convert support team if you would like to use a custom dimension value to correlate user activity across sessions & devices.
  • items (required)
    • A variable sized array of objects containing the ID's of the items which are eligible to be presented to the user. There is typically no reason to perform ranking requests when there are fewer than two items eligible for presenting.
    • If using Google Analytics as an analytics provider, item ID value should be the same value as used for tracking Product SKU related metrics.
    • When possible, the item's should be passed to Convert in the same (or original) order which the item's would have been presented to the customer if the Convert campaign were to be set as Inactive. The input order may be considered by the machine learning models as an input signal if it is found to be a useful in making more accurate predictions.
    • By default, customer campaigns are limited to ranking up to 100,000 items per rank request. Please contact the Avatria Convert support team if you'd like to request a higher limit.

For successful requests (response code 200), the response will contain the re-prioritized list of items including each item's associated score as a Number (signed decimal). A higher score indicate an item's stronger predicted relevance for the given query.

{
   "eventId":"5e04f486-d5f9-454b-9f2c-9190f88e7285",
   "items":[
      {
         "id":"B009W7HD16",
         "score":3.182
      },
      {
         "id":"B009VGRFKM",
         "score":3.013
      },
      {
         "id":"B00LPLHQ3W",
         "score":2.901
      },
      {
         "id":"B009Q0VAOK",
         "score":2.901
      }
   ]
}

In the event the rank request is not successful, a non-200 return code will be returned. If a non-200 return code is received, the body of the response will contain more details regarding the failure, including a reference number which can be used with the Avatria Convert support team for debugging issues. In production settings, when a non-200 return code is received, it is recommended to either retry the request or skip the re-prioritization step and show the items in the original order which was passed to Convert in the ranking request.

It is also recommended that clients configure a response time threshold to avoid negatively impacting the user experience if the Convert Relevance engine is not providing acceptable response times. Typical relevance engine response times is below 10 milliseconds (time to first byte) once the request has reached the server. A one-half to one second response time limit is usually recommended for typical consumer facing use cases.

For more information, please see the  Avatria Convert Relevance Engine API swagger docs.

Related articles