Before You Start

Request Types

Communication with the Gravity recommender system mostly consists of only two very basic request types, updates and recommendations. If you are already familiar with this, you can skip directly to the payload specifications or to the descriptions and examples underneath.

Updates

Whenever you send information to the system, you're updating it. For the recommender system, all and any incoming data are updates. The most common data type is information about users and their actions, but also information about products, like prices, descriptions, stock statuses etc, is ultimately inserted into the Sannsyn Recommender System as updates.

Short non-exhaustive glossary of update elements:

Entities — What an update concerns. Typically, entities are whatever items you sell (and want recommendations for) in your service, but also customers are actually entities. Any distinct, independent thing or being that the Gravity system handles, is an entity.
Cluster — An entity that maintains a relation to other entities. Most updates convey information about a cluster-entity relation (e.g. a customer-to-purchased-items relation), and thus contain both entities and a cluster.
What — The event that the update concerns. Usually, this is a noun referring to an action, like PURCHASE.
Data — An object containing extra information pertaining to the update. For most updates, this is may simply be left out.
Where — The place or sphere where the event took place, like web, app, email etc.
Origin — Where entities in the update originated. Mostly used to report recommendation exposures and recommendation clicks, as described further down.

Recommendations

All operations in the Gravity system that return something, are recommendations, even though some of them are simple counts or other basic computations. They have in common that they apply an algorithm to the aggregated data within the system, and the by far most common use of this, is for recommendations; hence the name.

Short non-exhaustive glossary of elements in recommendation requests:

Recommender — The ID of the chosen recommender. You may think of this as the name of an algorithm
Input — External information that the chosen recommender needs for its calculations. This might for instance be the ID of an entity to find similarities or inequalities with.

Clusters and entities alike are simple IDs (strings) combined with a taxon that describes the type of entity they represent. You can think of these taxa as simple labels, and usually they are just words like «person» or «item». You will need to specify them, however. Details about this, and about updates and recommendation requests and the JSON payloads to go along with such requests, are found in the payloads specification

Resources

Available functions and objects in the Sannsyn javascript based API are systematized in the JavaScript Client document.
Payloads expected and returned by the server when using the serverside http api are systematized in the Payload Specifications document.

Comments

We welcome comments, questions and improvement requests. Please send your remarks to Sannsyn support.