Metarank's API provides an easy way to integrate Metarank with your applications.
  • Feedback API receives the stream of events
  • Train API trains the model on your data
  • Ranking API provides personalized results generated by the trained model

API Endpoint: /feedback
Method: POST
Feedback endpoint receives several types of events: item, user, interaction, ranking.
Integrating these events is crucial for personalization to operate properly and provide relevant results.

You can find events and their description on the Supported events.

API Endpoint: /train/<model name>
Method: POST
Trrain endpoint runs the training on persisted data. You can run this method at any time to re-train the model.

API Endpoint: /rank/<model name>
Method: POST
Querystring Parameters:
  • explain: boolean: used to provide extra information in the response containing calculated feature values.
Ranking endpoint does the real work of personalizing items that are passed to it. You need to explicitly define which model to invoke.

"id": "81f46c34-a4bb-469c-8708-f8127cd67d27",// required
"timestamp": "1599391467000",// required
"user": "user1", // optional
"session": "session1", // optional
"fields": [ // optional
{"name": "query", "value": "jeans"},
{"name": "source", "value": "search"}
"items": [ // required
{"id": "item3", "relevancy": 2.0},
{"id": "item1", "relevancy": 1.0},
{"id": "item2", "relevancy": 0.5}
  • id: a request identifier later used to join ranking and interaction events. This will be the same value that you will pass to feedback endpoint for impression and ranking events.
  • user: an optional unique visitor identifier.
  • session: an optional session identifier, a single visitor may have multiple sessions.
  • timestamp: when this event happened. (see timestamp format description on which formats are supported)
  • fields: an optional array of extra fields that you can use in your model, for more information refer to Supported events.
  • items: which particular items were displayed to the visitor.
  • items.id: id of the content item. Should match the item property from item metadata event.
  • items.relevancy: a score which was used to rank these items. For example, it can be BM25/tfidf score coming from ElasticSearch. If your system doesn't return any relevancy score, just use 1 as a value.

"items": [
{"id": "item2", "relevancy": 2.0, "features": [{"name": "popularity", "value": 10 }]},
{"id": "item3", "relevancy": 1.0, "features": [{"name": "popularity", "value": 5 }]},
{"id": "item1", "relevancy": 0.5, "features": [{"name": "popularity", "value": 2 }]}
  • items.id: id of the content item. Will match item property from the item metadata event.
  • items.relevancy: a score calculated by personalization model
  • items.features: an array of feature values calculated by pesonaliization model. This field will be returned if explain field is set to true in the request. The structure of this object will vary depending on the feature type.
Copy link
Edit on GitHub
On this page
Payload format
Payload format
Response format