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)
Conversion	buy-category-pref	category name (multiple)
Item detail view Item quick-view	detail-view	product-id
Item detail view Item quick-view	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 Share Rate (optional; only capture positive ratings)	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"
}

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"
    },
    ...
]