This reference page demonstrates how to retrieve the list of fixtures we hold across all competitions, and explains how to interpret the data returned by our football API.
id of the fixture does not correspond to the id of the match once the match kicks off or concludes. However, the payload returned by the live scores api endpoint includes a field named fixture_id, which maps the match to its associated fixture. This same behavior applies to the football history matches api endpoint. Within that response, you will likewise encounter the fixture_id data field, and the ID of the live score match and the ID of the history match are consistently identical.This page walks you through retrieving the complete list of currently available fixtures. You will also discover the various filtering and traversal options at your disposal for navigating football fixtures data. In simple terms, a fixture represents a match that has been scheduled to take place in the future.
ENDPOINT
To retrieve the complete list of fixtures available through our football API feed, you simply need to send a request to the URL shown below. We provide fixture coverage for more than 400 national and international competitions across the globe. Read more about our competitions API endpoint.
Check this Football API endpoint in our postman collection. Download it now!
PARAMETERS
The fixtures API endpoint exposes a range of parameters that let you filter and navigate the data however you see fit. These parameters are outlined in the table below. You are free to combine them or use each one on its own.
| Name | Type | Required | Example | Description |
|---|---|---|---|---|
| competition_id | number | 16 | The id of the competition where the match is scheduled to take place. | |
| date | date/string | 2018-05-15/today | Limits the response to fixtures scheduled on that particular date. When you pass today as the value, our football API returns only the fixtures taking place today. | |
| group_id | number | 1456 | The ID of the competition group, used when you want to retrieve only the fixtures belonging to that specific group. | |
| lang | string | fa | A two letter language code following the ISO 639-1 standard. | |
| page | number | 2 | Returns only fixtures on that page that contain results. | |
| round | number/string | 19/R16 | Narrows the fixtures down to a specific round, provided the league supports rounds. This value may be numeric, such as 1, 5, or 10, or it may take the form of R16, QF, SF, and similar designations. | |
| team | number | 19 | Restricts the returned fixtures to those involving a specific team. |
RESPONSE
Each request returns a maximum of 30 fixtures matching the parameters supplied in the query URL. To move further into the future, follow the next page link included in the response. To step back, use the previous page link that the response also provides.
| Name | Type | Example | Description |
|---|---|---|---|
| away | object | {} | An object containing details about the away team in the fixture. It follows the structure of our standard team object. |
| competition | object | {} | An object containing details about the competition in which the fixture is scheduled to take place. It follows the structure of our standard competition object. |
| country | object | null | {} | An object containing details about the country where the fixture is scheduled to take place. It follows the structure of our standard country object. When the match belongs to an international competition such as the UEFA Champions League, the value of country will be null. |
| date | date | 2018-05-15 | The date on which the football match is scheduled to be played. |
| federation | object | null | {} | An object containing details about the federation in which the fixture is scheduled to take place. It follows the structure of our standard federation object. When the match belongs to a national competition such as the English Premier League, the value of federation will be null. |
| group_id | number | 1714 | The id of the group to which the fixture belongs. This proves especially useful for major competitions such as the FIFA World Cup or the CONMEBOL Copa America. |
| home | object | {} | An object containing details about the home team in the fixture. It follows the structure of our standard team object. |
| id | number | 1578384 | The id of the fixture. This value is permanent, allowing you to track the fixture even if it is rescheduled by the football association responsible for the competition in which the fixture takes place. |
| location | string | Torino | The venue or stadium where the match is scheduled to be played, or empty when sufficient data is not available. |
| odds | object | {} | An object containing information about the pre match and live match betting odds. It follows the structure of a standard odds object. |
| round | integer/string | 25/QF | The round of the match, also known as the matchday, for the football game. When accurate data is unavailable, the round number appears as 999. In the case of a direct elimination cup, this field may instead hold a string representation of the round, for example QF for Quarter Finals. |
| time | time | 12:00 | The kick off time of the football match. If accurate data is unavailable, the value will contain only zeros, for example 00:00. Every start date and time is expressed in the UTC timezone. |
{
"success": true,
"data": {
"fixtures": [
{
"time": "22:00:00",
"id": 1898655,
"date": "2026-10-06",
"round": "8",
"competition": {
"id": 481,
"is_cup": true,
"is_league": false,
"tier": 0,
"active": true,
"name": "Copa De La Division Profesional",
"national_teams_only": false,
"has_groups": false
},
"away": {
"name": "San Antonio Bulo Bulo",
"logo": "https:\/\/cdn.football-api.com\/teams\/7154.png",
"id": 7154,
"country_id": 60,
"stadium": "-"
},
"country": {
"fifa_code": "BOL",
"name": "Bolivia",
"flag": "BOL.png",
"uefa_code": "",
"id": 60,
"is_real": true
},
"home": {
"name": "Real Potosi",
"logo": "https:\/\/cdn.football-api.com\/teams\/277.png",
"id": 277,
"country_id": 60,
"stadium": "Estadio Victor Agust\u00edn Ugarte"
},
"odds": {
"pre": {
"1": null,
"2": null,
"X": null
},
"live": {
"1": null,
"2": null,
"X": null
}
},
"group_id": 0,
"location": "Estadio Victor Agust\u00edn Ugarte",
"federation": null
},
{
"time": "22:15:00",
"id": 1896733,
"date": "2026-10-06",
"round": "13",
"competition": {
"id": 49,
"is_cup": false,
"is_league": true,
"tier": 1,
"active": true,
"name": "Division Profesional",
"national_teams_only": false,
"has_groups": true
},
"away": {
"name": "Nacional Asuncion",
"logo": "https:\/\/cdn.football-api.com\/teams\/2208.png",
"id": 2208,
"country_id": 62,
"stadium": "Estadio Arsenio Erico"
},
"country": {
"fifa_code": "PAR",
"name": "Paraguay",
"flag": "PAR.png",
"uefa_code": "",
"id": 62,
"is_real": true
},
"home": {
"name": "Olimpia",
"logo": "https:\/\/cdn.football-api.com\/teams\/2384.png",
"id": 2384,
"country_id": 62,
"stadium": "Estadio Manuel Ferreira"
},
"odds": {
"pre": {
"1": 1.9499999999999999555910790149937383830547332763671875,
"2": 3.75,
"X": 3.100000000000000088817841970012523233890533447265625
},
"live": {
"1": null,
"2": null,
"X": null
}
},
"group_id": 0,
"location": "Estadio Manuel Ferreira",
"federation": null
}
],
"next_page": "https:\/\/api.football-api.com\/fixtures\/list.json?key={{demo_key}}&secret={{demo_secret}}&page=2",
"prev_page": false
}
}EXAMPLES
The examples below demonstrate how to call this endpoint in several programming languages, with no filters applied, in order to get all the fixtures. In this example, we have used the demo api key and secret pair.
If you login in, you will see all examples with your own api key and api secret
cUrl:
curl -XGET https://api.football-api.com/fixtures/list.json?key=demo_key\\&secret=demo_secretfile_get_contents('https://api.football-api.com/fixtures/list.json?key=demo_key\&secret=demo_secret');import urllib2
req = urllib2.Request('https://api.football-api.com/fixtures/list.json?key=demo_key\&secret=demo_secret')
response = urllib2.urlopen(req)
print response.read()The examples below illustrate how to retrieve all fixtures for today by leveraging the date filter of our fixtures football API.
cUrl:
curl -XGET https://api.football-api.com/fixtures/list.json?date=today&key=demo_key\\&secret=demo_secretfile_get_contents('https://api.football-api.com/fixtures/list.json?date=today&key=demo_key\&secret=demo_secret');import urllib2
req = urllib2.Request('https://api.football-api.com/fixtures/list.json?date=today&key=demo_key\&secret=demo_secret')
response = urllib2.urlopen(req)
print response.read()