# 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`.

{% hint style="info" %}

### 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.

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

{% endhint %}

{% hint style="info" %}

### 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`.

```bash
$ 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`.
{% endhint %}

## 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`.

{% hint style="info" %}

### 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.

```bash
$ 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.

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

{% endhint %}

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` |