# Time

Most of the API endpoints are time sensitive, e.g.

* Take popular events **within** the given **time frame**
* Get recommended events starting **after** the provided **timestamp**
* Get similar events starting **up to** the given **timestamp**

Time related parameters are consistent across all endpoints. In the following sections an overview of time handling in the API is provided.

## Time parameters

The following time related parameters exist:

* `from` - The starting timestamp in `YYYY-MM-DD hh:mm:ss` format, if not set defaults to the current timestamp
* `from_offset` - The offset to be applied on the `from` parameter
* `to_offset` - The offset to be applied on the `to` parameter

{% hint style="info" %}

### Parameters availability

Some endpoints may not support all time parameters. Make sure to check the documentation of each endpoint in order to figure out what is supported.
{% endhint %}

## Working with offsets

The API provides a generic system to create time ranges.

The `from`, `from_offset` and `to_offset` parameters are used to create the range `[from +/- from_offset, from +/- to_offset]`.

{% hint style="info" %}

### Offset format

`from_offset` and `to_offset` parameters accept a `number` followed optionally by `m`, `h`, `d` for minutes, hours and days respectively. The suffix must be only one character of \[`m`, `h`, `d`].

If no suffix is set, it defaults to minutes(`m`). Notice that the number can be any signed integer or float. Some examples follow:

* `-2h` - a negative offset of 2 hours
* `15m` - a positive offset of 15 minutes
* `7d` - a positive offset of 7 days
* `-30` - a negative offset of 30 minutes
  {% endhint %}

{% hint style="info" %}

### Time range example

In this example we get events beginning between 2020-07-02 17:00:00 and 2020-07-02 21:00:00. This is due to the time window we create:

`[2020-07-02 19:00:00 - 2h, 2020-07-02 19:00:00 + 2h]`

```bash
$ curl --request GET \\
  --url 'https://api.vaix.ai/api/sports/offering/events?from=2020-07-02%T19:00:00&form_offset=-2h&to_offset=2h'
```

{% endhint %}

{% hint style="info" %}

### Using the correct parameters

Most of the time you would want the produced time ranges to be dynamic, for example to fetch popular events starting within the next 24 hours from now. In these cases it is strongly advised not to use the `from` parameter and simply use the corresponding offset parameter, like the following example:

```bash
$ curl --request GET \\
  --url 'https://api.vaix.ai/api/sports/events/popular?from_offset=24h
```

Use the `from` parameter only if you want results for a static time range, for example \[`2022-05-04 19:00:00`, `2022-05-04 23:00:00`].
{% endhint %}

## Timezone

{% hint style="warning" %}

### UTC

All timestamps returned by the API and all input timestamps are expected to be in UTC. Make sure to convert your timestamps accordingly if you are using a different default timezone.
{% endhint %}


---

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