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

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.

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

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

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]

$ 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'

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:

$ 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].

Timezone

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.