Event Format
Metarank expects to receive a predefined set of events, describing visitor activity and item metadata:
  1. 1.
    Item metadata events. They describe what should be known about items.
  2. 2.
    User metadata events. They describe what we may know about visitors.
  3. 3.
    Ranking events. What was presented to the visitor.
  4. 4.
    Interaction events. What visitor did with the ranking (clicks, likes, purchases).

Metarank expects to receive these events in JSON format for simplicity. There is also a plan to add support for protobuf in some future version. Each event has a couple of shared required fields:
  • id - which is a unique identifier for the event, should be generated by your app
  • timestamp - number of milliseconds from 1970-01-01T00:00:00 (see timestamp format description on which formats are supported)
  • event - one of item/user/ranking/interaction values.
There is also a shared optional "tenant" field for multi-tenancy cases.

fields parameter is used in all events, however it is optional for ranking and interaction events. You can provide some additional context, like a search query, selected filters or shipping data that can be used as features of your personalization model.
"fields": [
{"name": "title", "value": "You favourite cat"}
]
fields.name: name of the field. fields.value: can be any of the following types:
  • boolean
  • string
  • number
  • list of strings
  • list of numbersr

Metadata event is used to provide Metarank with updates of your content items (new items added, updates of values for existing items). You don't need to pass all values that your items have; only the ones that you might use as your personalization model features.

{
"event": "item",
"id": "81f46c34-a4bb-469c-8708-f8127cd67d27",
"timestamp": "1599391467000", // required
"item": "item1", // required
"fields": [
{"name": "title", "value": "You favourite cat"},
{"name": "color", "value": ["white", "black"]},
{"name": "is_cute", "value": true}
]
}
  • id: event id. This field is not yet used, but the value must be provided at the moment.
  • item: id of the content item.
  • fields: an array of content item properties.

User metadata is useful when you have some extra knowledge about your visitor. For example, if visitor filled a signup form, it could be gender or age.

{
"event": "user",
"id": "81f46c34-a4bb-469c-8708-f8127cd67d27",
"timestamp": "1599391467000", // required
"user": "user1", // required
"fields": [
{"name": "age", "value": 33},
{"name": "gender", "value": "m"}
]
}
  • id: event id. This field is not yet used, but the value must be provided at the moment.
  • user: id of the visitor.
  • fields: an array of content item properties.

Ranking event is used to indicate what items and in what order are shown to a visitor. This information is used by personalization algorithms to understand which items are relevant for the visitor.

{
"event": "ranking",
"id": "81f46c34-a4bb-469c-8708-f8127cd67d27",// required
"timestamp": "1599391467000",// required
"user": "user1",// optional
"session": "session1",// optional
"fields": [
{"name": "query", "value": "cat"},
{"name": "source", "value": "search"}
],
"items": [
{"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. Should match the value that is sent to the Ranking API.
  • user: an optional unique visitor identifier.
  • session: an optional session identifier, a single visitor may have multiple sessions.
  • fields: an optional array of extra fields that you can use in your model, as described above.
  • items: which particular items were displayed to the visitor.
  • items.id: id of the content item. Should match the item property from metadata event.
  • items.relevancy: a score which was used to rank these items. You can use relevancy score returned by Metarank, or other score that your system generated. The value is optional and can be undefined.

Interaction event identifies which actions the visitor performed on the items displayed. Some of the example of such events are: click, like, purchase. The type field must match the name provided in the Configuration.

{
"event": "interaction",
"id": "0f4c0036-04fb-4409-b2c6-7163a59f6b7d",// required
"ranking": "81f46c34-a4bb-469c-8708-f8127cd67d27", //optional
"timestamp": "1599391467000",// required
"user": "user1",// optional
"session": "session1",// optional
"type": "purchase",// required
"item": "item1",// required
"fields": [
{"name": "count", "value": 1},
{"name": "shipping", "value": "DHL"}
],
}
  • id: a request identifier.
  • ranking: an optional identifier of the parent ranking event. Some interactions may happen outside of the ranking event (for example, likes happened on an item page), so it can be legally empty.
  • user: an optional unique visitor identifier.
  • session: an optional session identifier, a single visitor may have multiple sessions.
  • type: internal name of the event.
  • item: id of the content item. Should match the item property from metadata event.
  • fields: an optional array of extra fields that you can use in your model, as described above.
Copy link
Edit on GitHub
On this page
Event format
fields parameter
Item metadata event
Event format
User metadata event
Event format
Ranking event
Event format
Interaction event
Event format