Periods

The periods include allows you to retrieve information about different periods within a football match, such as regular time, extra time, and penalties. Including the periods in your API requests allows you to retrieve detailed information about the current minute and second of the fixture and the time that has already elapsed.

You can use the periods include by adding the &include= parameter and setting it to periods to retrieve this information. For a GET Fixture by ID request, that would look like this:

https://api.sportmonks.com/v3/football/fixtures/{fixture_ID}&include=periods

Fields

The "id" field serves as a unique identifier for each period, while the "fixture_id" corresponds to the associated fixture. The "type_id" field indicates the type of the period, and "started" and "ended" are UNIX timestamps representing the period's start and end times, respectively. The "counts_from" field denotes the minute from which the period starts counting, and "ticking" is a boolean that signifies whether the period is currently being played. The "sort_order" field establishes the order of the period, and the "description" field provides a textual description. The "time_added" field represents how much time was added to that period, and "period_length" represents the scheduled length of the period. Information on the current minute and seconds of the period can be found in the "minutes" and "seconds" fields, respectively. The "has_timer" boolean indicates whether detailed timer information is available for minutes and seconds.

How does it work?

When you use periods in a regular match, you'll get two different period IDs. If the match goes into extra time or penalties, a new and unique period ID will be created and shown in the response. Look at the example of a World Cup final below:

Periods example World Cup 2022 Final: Argentina - France

        "periods": [
            {
                "id": 4539357,
                "fixture_id": 18452325,
                "type_id": 1,
                "started": 1671378775,
                "ended": 1671382962,
                "counts_from": 30,
                "ticking": false,
                "sort_order": 1,
                "description": "1st-half",
                "time_added": 7,
                "period_length": 45,
                "minutes": null,
                "seconds": null,
                "has_timer": false
            },
            {
                "id": 4539396,
                "fixture_id": 18452325,
                "type_id": 2,
                "started": 1671379669,
                "ended": 1671382908,
                "counts_from": 45,
                "ticking": false,
                "sort_order": 2,
                "description": "2nd-half",
                "time_added": 3,
                "period_length": 45,
                "minutes": null,
                "seconds": null,
                "has_timer": false
            },
            {
                "id": 4539412,
                "fixture_id": 18452325,
                "type_id": 3,
                "started": 1671385452,
                "ended": 1671385485,
                "counts_from": 105,
                "ticking": false,
                "sort_order": 3,
                "description": "extra-time",
                "time_added": null,
                "period_length": 30,
                "minutes": null,
                "seconds": null,
                "has_timer": false
            },
            {
                "id": 4539415,
                "fixture_id": 18452325,
                "type_id": 5,
                "started": null,
                "ended": null,
                "counts_from": 120,
                "ticking": false,
                "sort_order": 4,
                "description": "penalties",
                "time_added": null,
                "period_length": null,
                "minutes": 120,
                "seconds": null,
                "has_timer": false
            }

Other include options

In addition to the periods include you can use the currentPeriod include. This allows you to retrieve the inplay period in a more convenient way compared to using the periods include. Please note that include may return NULL. For example, when the match has not yet started, is in half-time, or has ended.

Other include options are:

• periods.statistics which gives statistics for each period

• periods.events which shows specific events in each period

• periods.timeline which displays the timeline for a period

• periods.type which helps you get the type of a specific period.