Timezone parameters on different endpoints

When working with APIs that provide sports data, understanding the distinction between Get Fixtures by Date endpoints and other endpoints like Livescore is crucial, particularly when it comes to handling timezone parameters. Let's explore the key differences between these two types of endpoints in relation to time zones.

Livescore Endpoint - GET All Livescores

The livescore endpoint provides information about fixtures that are currently in progress, starting within the next 15 minutes, or ending within the past 15 minutes. It is important to note the following characteristics of the livescore endpoint:

If you add a timezone to the Livescore endpoint, this will only have an impact on the starting_at field which will be converted to your preferred time zone.

Regardless of whether you include a timezone parameter in the API request or not, the API response remains the same.

The endpoint returns fixtures in Coordinated Universal Time (UTC) based on the specified criteria of being 15 minutes before the start time, currently in play, or 15 minutes after the end time.

Fixture by Date Endpoint - GET Fixture by Date

The Fixture by Date endpoint functions differently from the livescore endpoint and provides fixtures based on a specific date. When using this endpoint with a timezone parameter, it is crucial to understand the following behaviour:

Unlike passing the timezone in other endpoints, passing the timezone in these endpoints brings a special functionality: passing the time zone here will directly affect your query. This is for example useful for building your own schedule depending on your timezone!

For example, let's check a match between Flamengo and Racing Club in the Copa Libertadores . That fixture has a start time of 00:00 UTC on June 9, 2023, and 21:00 on June 8, 2023, in the America/Fortaleza time zone. In this scenario:

If you use the following API request without a timezone parameter:

https://api.sportmonks.com/v3/football/fixtures/date/2023-06-08

The Copa Libertadores fixture will not be included in the response.

However, if you include the timezone=America/Fortaleze parameter in the API request:

https://api.sportmonks.com/v3/football/fixtures/date/2023-06-08&timezone=America/Fortaleza

The Copa Libertadores match will be included in the response.

You can see the difference in the two requests down below.

With Timezone parameter

{
            "id": 18809508,
            "sport_id": 1,
            "league_id": 1122,
            "season_id": 21019,
            "stage_id": 77461320,
            "group_id": 248643,
            "aggregate_id": null,
            "round_id": 303508,
            "state_id": 5,
            "venue_id": 392,
            "name": "Flamengo vs Racing Club",

            "result_info": "Flamengo won after full-time.",
            "leg": "1/1",
            "details": null,
            "length": 90,
            "placeholder": false,
            "has_odds": true,
            "starting_at_timestamp": 1686268800
        },

Without Timezone parameter

        {
            "id": 18809508,
            "sport_id": 1,
            "league_id": 1122,
            "season_id": 21019,
            "stage_id": 77461320,
            "group_id": 248643,
            "aggregate_id": null,
            "round_id": 303508,
            "state_id": 5,
            "venue_id": 392,
            "name": "Flamengo vs Racing Club",
 
            "result_info": "Flamengo won after full-time.",
            "leg": "1/1",
            "details": null,
            "length": 90,
            "placeholder": false,
            "has_odds": true,
            "starting_at_timestamp": 1686268800
        },