Recommendations API

Integrate recommendations into any site or application using SiteSpect Recommendations API

Table of Contents

Sending Events to the API

       Event Types

Retrieving Recommendations Using the API

       Query Fields

       Rules

SiteSpect's 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.

Sending Events to the API

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

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

{
   "events_recorded": true
}

Events Types

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

• All values must stay consistent within their event type.   
• Product IDs must match the Product IDs in the Product Feed.

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.

 At a Glance:

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

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

Queries Request Format

The request body should be a JSON object with the following fields

Required Fields

• num: The number of results requested (max 50).

• algorithm: The recommendation algorithm to use. Possible values include:

  • personalized: Requires "user" field, backfills with popular if necessary.

  • recently-viewed: Requires "user" field, does not backfill.

  • people-also-like: Requires "itemSet"; may use "user" for fallback; backfills with popular.

  • complementary: Requires "itemSet"; may use "user" for fallback; backfills with popular.

  • popular: Uses the current popularity model (e.g., trending, hot, popular, etc.).

• rules: An array (can be empty) defining business rules for filtering, boosting, or excluding results.  See below for more detail.

Optional Fields

• user: SiteSpect user GUID (required for some algorithms).

• itemSet: Array of one or more product SKUs that match SKUs from the product feed (required for some algorithms).

• rules: Array of 0 or more business rules. Rules modify the recommendation results by filtering or adjusting their ranking. Effectively, rules override the algorithm to varying degrees, so we recommend using them primarily for merchandising and to avoid dissonant results.

• actionSkus: optional Array of 1 or more product SKUs that represent the current item or current page context. These will be used for populating current item’s <fieldname> in rules (see below).

Example API requests by Algorithm

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

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

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

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

Example of Recommendations Response

Response fields are configurable based on your Product Feed.  

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

Rules

Rule Builder

The easiest way to generate rules is by using the Filter & Boost tab when building a Recommendation Campaign. Expert Mode shows a JSON representation of the rule. The actions property of each rule from the rule builder contains an object that can be used in the rules array.

Manually building a rule

Each rule is a json object with the following 3 properties:

• name: The field name, as found in the product feed or rule builder.

• bias: Defines how the rule influences recommendations:

  • -1: Include only items matching this rule (may return fewer results than requested).

  • 0: Exclude items matching this rule (may return fewer results than requested).

  • 0.001 - 0.999: Deboost matching items.

  • 1: No effect.

  • >1: Boost matching items (e.g., 2 = 100% boost in UI).

• values: An array of case-sensitive strings. Items must match one or more values for the rule to apply. To specify a Current Item’s field as the value, make sure actionSkus (above) is populated and use

  {"var":"<fieldname>"}

Multiple Rule Values

• Boosting: Each matched value increases the boost separately.

• Include/Exclude Logic:

  • Values in a single rule are OR'd together.

  • To create AND conditions, define multiple rules.

Example Rules

OR condition: Include only if "Brand" is "Patagonia" OR "North Face".

AND condition: Include only if "Features" includes both "Goretex" AND "Vibram Sole".