Recommendations API

Integrate recommendations into any site or application using SiteSpect Recommendations API

Our Recommendations solution offers a full set of APIs to send events to the model and to get recommendations.

Refer to our Guide for getting started with recommendations for details on setting up your catalog and loading historical data.

Events API Endpoint

The Events API endpoint enables you to send events about user behaviors and item preferences.

Endpoint:

https://recs.sitespect.net/v1/[side-id]/recs/

Example payload for events:

{
    "events": [
        {
            "name": "detail-view",
            "entityIds": [
                "173608"
            ]
        },
        {
            "name": "detail-category-pref",
            "entityIds": [
                "Category 1",
                "Category 2"
            ]
        }
    ],
    "userId": "G6839736557633606790"
}

Successful response for events:

{
   "events_recorded": true
}

Events Table

Refer to this table for the list of events and their expected values for events API endpoint.

User Action

name

entityIds
(multiple: an array of values)

Conversion

buy

product-id (multiple)

buy-category-pref

category name (multiple)

Item detail view
Item quick-view

detail-view

product-id

detail-category-pref

category name

Category page view

category-view

category name

Search results page view

search-string

Raw searched expression

Like
Share
Rate
(optional; only capture positive ratings)

like-detail-view

product-id

like-category-pref

category name

Retrieving Recommendations Using the API

You can include Recommendations in your app with a simple API call. The response from the Recommendations API provides a JSON object that exposes recommended items with their associated attributes (e.g. price, name, link, image link, ...).

 

Business rules can be set as part of the request payload to include/exclude/boost/deboost Recommendations based on many attributes.

 

API endpoint for retrieving recommendations:

https://recs.sitespect.net/v1/[site-id]/recs/

 

People Also Like

Example API request payload for “People Also Like”, including a boost filter on parent category:

{
    "item": "228930",
    "rules": [
        {
            "name": "parentCategory",
            "bias": 11,
            "values": [
                "Parent Cat 1",
                "Parent Cat 2"
            ]
        }
    ],
    "num": 20,
    "algorithm": "people-also-like"
}

Complementary

Example API request payload for “Complementary”:

{
    "itemSet": [
        "D107",
        "B890"
    ],
    "rules": [],
    "num": 20,
    "algorithm": "complementary"
}

Personalized

Example API request payload for “Personalized”:

{
    "user": "G6769572760122298386",
    "rules": [],
    "num": 20,
    "algorithm": "personalized"
}

Popular

Example API request payload for “Popular”:

{
    "rules": [],
    "num": 20,
    "algorithm": "popular"
}

Recently Viewed

Example API request payload for “Recently Viewed”:

{
    "user": "G6769572760122298386",
    "num": 20,
    "algorithm": "recently-viewed"
}

Example of Recommendations Response

[
    {
        "id": 176726,
        "sku": "4324321",
        "clientId": 5,
        "link": "https://www.site.com/store/product/microfiber-sheet-set/4324321",
        "price": "59.99",
        "product_type": "Sheet Sets",
        "name": "400-Thread-Count Solid Sateen Sheet Set",
        "available": "true"
    },
    {
        "id": 176725,
        "sku": "3543534",
        "clientId": 5,
        "link": "https://www.site.com/store/product/comfort-wrinkle-resistant-stripe-sheet-sheet/543534",
        "price": "39.99",
        "product_type": "Sheet Sets",
        "name": "Wrinkle Resistant Stripe Sheet Sheet",
        "available": "true"
    },
    ...
]