UpsideAI REST API

Overview

The UpsideAI REST API exposes all the endpoints required to train, configure and query for recommendations. This document provides a detailed description of the requirements and steps necessary to implement a fully functioning recommendation system.

Setup & Requirements

  1. To access these services, you will first need a valid api key.
  2. To access the API, all requests must be made using HTTPS
  3. The body of all requests and responses are always a JSON object or array and encoded as UTF-8

Recommendations

Key Concepts

UpsideAI Recommendations provides the ability to suggest to users one or more types of recommended products. These recommendations may be based on popular or trending items, personalized items based on an individual users’ preferences, items similar to another item, and more. Also, filters can be applied to each of these queries to extract a specific subset of products e.g. by category, color, size …

It’s important to understand that the information used to generate recommendations comes from the interactions your users have on your website. For instance, a user sees a thumbnail of a product that looks interesting and clicks on it to view the product page. Once on the details page, they scroll down to view the product specifications. The user then adds the product to the cart and subsequently completes the checkout process to purchase the product. These are all examples of user interactions.

There are several types of recommendations that can be presented to users and each of these can be filtered. For example, your site has a landing page for shoes and one for jackets. When a user arrives on the shoes landing page, you may wish to display personalized recommendations, but limit these to shoes rather than jackets. This is done with the use of tags.

Although tags can be any type of information, when recommending products tags usually represent product attributes: category, color, size, price, brand … Using tags is not required for querying recommendations, only to filter them. To add tags, a list of product id’s and their corresponding tags needs to be uploaded to the recommendation engine.

As the recommendation engine is using machine/deep learning, it requires a learning phase where the interactions are analysed and learnt by the system. The time to learn the system will depend on the number and frequency of interactions.

Recognizing users

When calling any endpoints that require identifying the user, a unique userID (int64) is required to track the history of each individual user. If your user is logged in then you should use your internal userId. However, many shoppers may browse a site for long periods before logging in, and sometimes of different sessions. In this case a unique id should be generated and assigned to these users and persisted locally (e.g. cookie or local storage). Make sure that any locally persisted information does not expire.

Interactions

POST: /interaction

Description: Adds a user interaction to the Learning engine.

Parameters:

  • Action: Identifies the specific action taken by a user, for a specific item (see details below). Required.

Example:

Requestcurl 	-X POST "https://api.upsideai.com/gateway/{ACCOUNT_NUMBER}/interaction" \
 	 	 	-H "Authorization: Bearer {KEY}" \
 	 	 	-H "Content-Type: application/json" 
 	 	 	-d "{ \"items\": [ \"1076\" ], \"type\": \"item_viewed\", \"user\": 2211}"

Notes:

The Action object accepts an array of items. This allows sending certain types of interactions in batch mode, such as when a user adds multiple items to a cart or checks-out multiple items.

POST: /tag

Description: Qualifies an item by tagging it with one or more tags e.g. product attributes.

Parameters:

  • ItemTag: Identifies the list of tags to add for a specific item (see details below). Required.

Example:

Requestcurl 	-X POST "https://api.upsideai.com/gateway/{ACCOUNT_NUMBER}/tag" \
 	 	 	-H "Authorization: Bearer {KEY}" \
 	 	 	-H "Content-Type: application/json" 
 	 	 	-d "{ \"itemId\": \"1076\", \"tags\": [ \"sales\", \"green\" , \"$100\"]}"

Notes:

When changes are made to product attributes, the tags will need to be updated for all affected products. Tagging a product will delete any previous tags that may have been applied, therefore updates should include all tags for an item, not only the ones that have changed.

DELETE: /tag

Description: Removes one or more tags from an item.

Parameters:

  • ItemTag: Identifies the list of tags to add for a specific item (see details below). Required.

Example:

Requestcurl 	-X DELETE "https://api.upsideai.com/gateway/{ACCOUNT_NUMBER}/tag" \
 	 	 	-H "Authorization: Bearer {KEY}" \
 	 	 	-H "Content-Type: application/json" 
 	 	 	-d "{ \"itemId\": \"1076\", \"tags\": [ \"sales\", \"green\" ]}"

Notes:

Contrarily to when tags are added, deleting tags will only remove the specified tags, not all tags associated to an item.

Recommendations

GET: / recommended-items

Description: Returns a list of personalized recommendations, based on the user’s past interactions

Parameters:

  • count: Specifies the number of items to return. Type: int32. Default: 10
  • shuffle: When False, the returned items will be ordered by their ranked value. When True, the returned items will be ordered randomly. Type: Boolean. Default: True.
  • tags: Specifying one or more tags allows filtering the returned items by the tag values e.g. ‘shoes’ + ‘hiking’. Type: array[string]. Optional
  • users: The id of one or more users, used to personalize the returned items. Required.

Example:

Requestcurl 	-X GET "https://api.upsideai.com/gateway/{ACCOUNT_NUMBER}/recommended-items?count=3&tags=red&tags=shoe&users=1612" 
 	 	 	-H "Authorization: Bearer {KEY}" \
 	 	 	-H "Accept: application/json" 
Response 	[
 	  {
 	    "item": "4382"
 	  },
 	  {
 	    "item": "1411"
 	  },
 	  {
 	    "item": "1504"
 	  }
 	]

GET: / trending-items

Returns a list of items that are currently trending. Trending items are ones that are gaining momentum and interest but may not be the most popular. The list of trending items is not personalized by user.

Parameters:

  • count: Specifies the number of items to return. Type: int32. Default: 10
  • shuffle: When False, the returned items will be ordered by their ranked value. When True, the returned items will be ordered randomly. Type: Boolean. Default: True.
  • tags: Specifying one or more tags allows filtering the returned items by the tag values e.g. ‘shoes’ + ‘hiking’. Type: array[string]. Optional

Example:

Request-X GET "https://api.upsideai.com/gateway/{ACCOUNT_NUMBER}/trending-items?count=3&tags=red&tags=shoe&shuffle=false" 
 	 	 	-H "Authorization: Bearer {KEY}" \
 	 	 	-H "Accept: application/json" 
Response 	[
 	  {
 	    "item": "5572"
 	  },
 	  {
 	    "item": "7133"
 	  },
 	  {
 	    "item": "2148"
 	  }
 	]

GET: / popular-items

Returns a list of the most popular items, defined by the overall sum of interactions. The list of popular items is not personalized by user.

Parameters:

  • count: Specifies the number of items to return. Type: int32. Default: 10
  • shuffle: When False, the returned items will be ordered by their ranked value. When True, the returned items will be ordered randomly. Type: Boolean. Default: True.
  • tags: Specifying one or more tags allows filtering the returned items by the tag values e.g. ‘shoes’ + ‘hiking’. Type: array[string]. Optional

Example:

Requestcurl 	-X GET "https://api.upsideai.com/gateway/{ACCOUNT_NUMBER}/popular-items?count=3&shuffle=true" 
 	 	 	-H "Authorization: Bearer {KEY}" \
 	 	 	-H "Accept: application/json" 
Response 	[
 	  {
 	    "item": "6922"
  	 },
 	  {
 	    "item": "4663"
 	  },
 	  {
 	    "item": "9061"
 	  }
 	]

GET: / hybrid-recommendation

The hybrid recommendation will return a mixed list of items from popular, trending and recommended items.

Parameters:

  • count: Specifies the number of items to return. Type: int32. Default: 10
  • tags: Specifying one or more tags allows filtering the returned items by the tag values e.g. ‘shoes’ + ‘hiking’. Type: array[string]. Optional
  • users: The id of one or many users, used to personalize the returned items. Type: array[string]. Optional.

Example:

Requestcurl 	-X GET "https://api.upsideai.com/gateway/{ACCOUNT_NUMBER}/hybrid-recommendation?count=3&tags=shoes&users=123" 
 	 	 	-H "Authorization: Bearer {KEY}" \
 	 	 	-H "Accept: application/json" 
Response 	[
 	  {
 	    "item": "5904"
 	  },
 	  {
 	    "item": "7420"
 	  },
 	  {
 	    "item": "2543"
 	  }
 	]

GET: / similar-items

Returns a list of items that are considered similar to the specified item(s). The list of similar items is not personalized by user.

Parameters:

  • count: Specifies the number of items to return. Type: int32. Default: 10
  • items: An array of one or more items. Type: array[string]. Required.
  • shuffle: When False, the returned items will be ordered by their ranked value. When True, the returned items will be ordered randomly. Type: Boolean. Default: True.
  • tags: Specifying one or more tags allows filtering the returned items by the tag values e.g. ‘shoes’ + ‘hiking’. Type: array[string]. Optional

Example:

Requestcurl 	-X GET "https://api.upsideai.com/gateway/{ACCOUNT_NUMBER}/similar-items?count=3&items=7639" 
 	 	 	-H "Authorization: Bearer {KEY}" \
 	 	 	-H "Accept: application/json" 
Response 	[
 	  {
 	    "item": "7765"
 	  },
 	  {
    "item": "9076"
 	  },
 	  {
 	    "item": "3948"
 	  }
 	]

Model

Action: Identifies the specific action taken by a user, for a specific item

Properties:

items: An array of one or more item id’s (products, content, etc.) for which the action occurred. Type: array[string]. Required.

type: The type of action that was taken by the user. Must be one of the following values:

  • item_viewed: the user selected an item to be viewed
  • details_viewed: when viewing an item, the user scrolled to view one or many additional details of the item
  • added_to_cart: in the case where the item is a product, the item was added to the cart
  • purchased: the item was purchased by completing the checkout process
  • liked: the user explicitly liked the item, or wrote a positive comment about the item
  • disliked: the user explicitly disliked the item, or wrote a negative comment about the item

Type: string. Default: item_viewed.

user: The id of the user that performed the action. Type: int64. Required.

ItemTag: Identifies the list of tags to add for a specific item

Properties:

itemId: The Id of the item that is being tagged. Type: string. Required.

tags: One or more tags to qualify the specified item. Type: array[string]. Required.