Gravity Recommender APIv1.1
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.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.
- Data — An object containing extra information pertaining to the update. For most updates, this is may simply be left out.
- What — The event that the update concerns. Usually, this is a noun referring to an action, like
PURCHASE. - Where — The place or sphere where the event took place, like
web,app,emailetc. - Origin — Where the system entities in the update were produced. Mostly used to report recommendation exposures and recommendation clicks.
Recommendations
All operations in the Gravity system that return something, are recommendations, even though some of them are simple counts or other basic computations. Recommendations have in common that they apply an algorithm to the aggregated data within the system.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 many of the built-in recommenders, this is optional.
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 Gravity javascript 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.
