Set up Aqurate Personalize via RESTful API

Learn which endpoints you need to call, what resources to access, and what fields to request.

Table of contents:

1. Authentication

2. Get product recommendations

2.1 Item-to-item recommendations

2.1.1 Item-to-item recommendations by product_id

2.1.2 Item-to-item recommendations by batches

2.2 User-to-item recommendations

1. Authentication

To query the endpoints, you need to generate an API key on the API Keys management page. You should generate a custom key with the scopes read:item_recs and read:user_recs.

When making API calls, use the generated API key for the X-Auth-Token parameter.

2. Get product recommendations

The Aqurate Personalize API offers two types of endpoints:

• Item-to-item endpoints
• User-to-item endpoints

2.1 Item-to-item recommendations

Item-to-item recommendations are centered around items, and are usually used on Product Detail Pages, Shopping Cart, and Pop-ups. There are multiple different resources, like recs/item/upsell, recs/item/cross-sell, recs/item/substitutes etc.

All of these endpoints:

• have the same parameters
• deliver responses of the same JSON structure
• require choosing the number of recommendations you want to retrieve for each product. This number can be specified with the top parameter. The default value is 10.

2.1.1 Item-to-item recommendations by product_id

↗️ Request

Querying by product_id simply involves passing the identifier of a specific product as an argument to the product_id parameter.

💡 Example API call: /recs/item/similar?top=10&product_id=12345.

↩️ Response

If recommendations are available for the product, you get a response that looks like this:

{
    "recs":
    [
        {
            "product_id": "45678",
            "sku_name": "45678",
            "rec_product_id": "901011",
            "position": 1
        },
        {
            "product_id": "45678",
            "sku_name": "45678",
            "rec_product_id": "12131415",
            "position": 2
        },
        <...>
    ]
}

The response contains a list of recommendations (the recs object) which have these fields:

1. product_id corresponds to the argument value passed to the query in the first place
2. rec_product_id specifies the recommended product
3. position provides the rank in the set of all recommendations. 

2.1.2 Item-to-item recommendations by batches (optional)

↗️ Request

A more efficient way of querying the complete set of recommendations is using the endpoint's batch functionality. You can do so by specifying the limit parameter (instead of the product_id parameter).

With the limit parameter, you can choose how many recommendations you want to retrieve per API call. This number should not be higher than 5,000 as the response may take too long.

💡 Example of an initial API call: /recs/item/similar?top=10&limit=1000.

↩️ Response

The first call to the API will give a response of this format:

{
    "recs":
    [
        {
            "product_id": "1234",
            "sku_name": "1234",
            "rec_product_id": "4567",
            "position": 1
        },
        {
            "product_id": "1234",
            "sku_name": "1234",
            "rec_product_id": "8910",
            "position": 2
        },
                <...>,
        {
            "product_id": "898989",
            "sku_name": "898989",
            "rec_product_id": "787878",
            "position": 3
        }
    ],
    "links":
    {
        "next": "https//api.aqurate.ai/recs/item/similar?top=10&limit=1000&marker=898989"
    }
}

The response contains two objects:

1. recs → similar to the one described in the previous section
2. next → contains the next field, which holds the URL that can be used to retrieve the next batch

By calling the next link after each API call, you retrieve the entire set of recommendations in our database. The responses have the same structure as the response above. Again, the product_id field corresponds to the item for which the rec_product_id is recommended.

You then perform API calls until the next field is null, which means that all recommendations have been retrieved:

{
    "recs":
    [
        {
            "product_id": "676767",
            "sku_name": "676767",
            "rec_product_id": "2233",
            "position": 1
        },
                <...>
    ],
    "links":
    {
        "next": null
    }
}

2.2 User-to-item recommendations

User-to-item recommendations are centered around users, and are usually used on Home Pages, Pop-ups, and via Email. The resource to use is: recs/user.

↗️ Request

Querying by user simply involves passing the identifier of a specific user as an argument. You can pass in the value of email, user_id, customer_id or cookie_id in the user field. There is no need to specify the identifier type.

As an overview, these are the types of identifiers supported.

💡 Example API call: /recs/user?top=10&user=support@aqurate.ai.

↩️ Response

If recommendations are available for the user, you get a response that looks like this:

{
  "recs": [
    {
      "user_id": "string",
      "user": "string",
      "user_type": "string",
      "product_id": "string",
      "position": 0
    }
  ],
  "links": {
    "next": "string"
  }
}

You’re done 🎉!

Questions about using our API? We're excited to help: support@aqurate.ai