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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sportradar.com/personalization/overview/using-the-api/ordering.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.