Ordering

The API provides two ways for sorting the data returned from an endpoint, called reorder_by and order_by. Reorder by can tweak the confidences of the items by using another metric to additionally rank them, while order by groups and sorts the produced output before rendering the results. None, one of them or both of them can be used in the same request. Reorder by has precedence over order by and it will be used first in case both of them are specified. Note that not all endpoints support these parameters.

Reorder by

Reorder by can be used to tweak the confidences of a resource by reranking with the confidences of one or more other resources.

To reorder the results, simple add the reorder_by=[metric]:[weight] query parameter to the url of the endpoint. Multiple reordering parameters may be specified by separating each one by a comma. Notice that each weight should be in the range (0,1]. The initial metric's weight will be 1 - weight.

Simple reordering example

In this example we fetch the 15 most popular games and then rerank them taking into account the recommendation confidence of user 1. In other words, each game will be ranked 50% based on its popularity and 50% based on its personalized score.

$ curl --request GET \\
  --url 'https://api.vaix.ai/api/casino/games/popular?user=1&count=15&reorder_by=recommended:0.5'

Reordering completely based on recommendation score

In this example we fetch the 15 most popular games and then rerank them completely based on the recommendation confidence of user 1, by setting the recommended weight to 1.

$ curl --request GET \\
  --url 'https://api.vaix.ai/api/casino/games/popular?user=1&count=15&reorder_by=recommended:1'

Q: What is the difference between this functionality and simply calling the recommended games endpoint?

A: The important difference here is that while the recommended games endpoint would rank all the available games based on the given user's preferences, this endpoint allows to rerank only the top games of a specific category, e.g popular/new/hot.

Order by

The API provides a generic system to order the returned items based on the values of specific fields.

To order the results, simply add the order_by=[operator][field] query parameter to the url of the endpoint. Multiple ordering parameters may be specified by separating each one by a comma. Notice that in this case, the order of the provided parameters will be used to order. This means that +field1,+field2 will provide different results than +field2,+field1.

Simple ordering example

In this example we get the recommended events for the user with id 1, grouped on league level with the most relevant league on top. Inside each league the events are ordered by begin time with the most recent one on top.

$ curl --request GET \\
  --url 'https://api.vaix.ai/api/sports/events/recommended?user=1&order_by=-league_confidence,%2Bbegin'

As mentioned above, having the order of the order_by parameters swapped would provide different results. The events would be sorted based on begin with the most recent ones on top. Those having the same begin time would be sorted by their league_confidence, with the most relevant league on top.

$ curl --request GET \\
  --url 'https://api.vaix.ai/api/sports/events/recommended?user=1&order_by=%2Bbegin,-league_confidence'

Not all endpoints support field selection. If ordering is available for an endpoint, then the supported ordering fields are indicated in the documentation of that endpoint.

Ordering operators

The following operators are supported by the API:

Operator	Description
+	Sorts the results based on the provided field's value in ascending order, e.g. +confidence
-	Sorts the results based on the provided field's value in descending order, e.g. -confidence