Getting Started
Endpoint overview
Tutorials
Tools
How-to Guides
API References
General
How-to build your API requests
We'll cover how to build correct API requests with our Football API 2.0
In this guide, we’ll be covering how to build API requests with our football API 2.0. The example API request will be focused on getting all the football matches on a certain date by using the fixtures by date endpoint. Fixtures is the terminology used for matches.
We’ll be working with a free plan, so we only have access to the Danish Superliga (id: 271) and the Scottish Premiership (id: 501).
Step 1: Get the base URL
The first thing we need to have is our base URL and our API token.
Base URL
1
https://soccer.sportmonks.com/api/v2.0/?api_token={API_TOKEN}
Copied!
Step 2: Choose and add the endpoint
Next, we need to add an endpoint to the base URL. As stated earlier, for this example we want to get all of the fixtures on a certain date. The endpoint for that is called fixtures by date. This will transform our URL into:
1
https://soccer.sportmonks.com/api/v2.0/fixtures/date/{Date}?api_token={API_TOKEN}
Copied!
The date has to be in the format of YYYY-MM-DD. In this example, we’ll take the date of 2020-09-26.
1
https://soccer.sportmonks.com/api/v2.0/fixtures/date/2020-09-26?api_token={API_TOKEN}
Copied!
Step 3: Evaluate the response
The football API 2.0 will return a ton of information, but the main takeaway is that there are various ids about the fixture, league, season, stage, etc. Other than that, there is also score, time, coaches and standings. Below is a snippet of the output.
1
{
2
"data": [
3
{
4
"id": 16475331,
5
"league_id": 501,
6
"season_id": 17141,
7
"stage_id": 77447501,
8
"round_id": 194976,
9
"group_id": null,
10
"aggregate_id": null,
11
"venue_id": 14509,
12
"referee_id": 15815,
13
"localteam_id": 338,
14
"visitorteam_id": 282,
15
"winner_team_id": null,
Copied!
Step 4: Enrichment
This guide would be pretty short if we were to end here. That’s why we’ll now be enriching our API request with includes. Here is the URL we used previously again.
1
https://soccer.sportmonks.com/api/v2.0/fixtures/date/2020-09-26?api_token={API_TOKEN}
Copied!
We might be interested in the teams that will be playing against each other. We can then add the following part to our request:
&includes=localTeam,visitorTeam. Now our URL will be:1
https://soccer.sportmonks.com/api/v2.0/fixtures/date/2020-09-26?api_token={API_TOKEN}&include=localTeam,visitorTeam
Copied!
Step 5: Re-evaluate response
Now we have more information about the local and visitor teams. The local team is called Hamilton Academical, with team id 338 and the visitor team is called Dundee United with team id 282.
1
"localTeam": {
2
"data": {
3
"id": 338,
4
"legacy_id": 693,
5
"name": "Hamilton Academical",
6
"short_code": "HMA",
7
"twitter": null,
8
"country_id": 1161,
9
"national_team": false,
10
"founded": 1874,
11
"logo_path": "https://cdn.sportmonks.com/images//soccer/teams/18/338.png",
12
"venue_id": 288196,
13
"current_season_id": 17141
14
}
15
},
16
"visitorTeam": {
17
"data": {
18
"id": 282,
19
"legacy_id": 692,
20
"name": "Dundee United",
21
"short_code": "DUD",
22
"twitter": null,
23
"country_id": 1161,
24
"national_team": false,
25
"founded": 1909,
26
"logo_path": "https://cdn.sportmonks.com/images//soccer/teams/26/282.png",
27
"venue_id": 8947,
28
"current_season_id": 17141
29
}
Copied!
Step 6: Go even further beyond
We can go even further beyond, by using nested includes. Let’s say we would like to know more about the coach of the visitor team. We simply add
.coachto visitorTeam. The URL then becomes this:1
https://soccer.sportmonks.com/api/v2.0/fixtures/date/2020-09-26?api_token={API_TOKEN}&include=localTeam,visitorTeam.coach
Copied!
1
"visitorTeam": {
2
"data": {
3
"id": 282,
4
"legacy_id": 692,
5
"name": "Dundee United",
6
"short_code": "DUD",
7
"twitter": null,
8
"country_id": 1161,
9
"national_team": false,
10
"founded": 1909,
11
"logo_path": "https://cdn.sportmonks.com/images//soccer/teams/26/282.png",
12
"venue_id": 8947,
13
"current_season_id": 17141,
14
"coach": {
15
"data": {
16
"coach_id": 896498,
17
"team_id": 201,
18
"country_id": 1161,
19
"common_name": "M. Mellon",
20
"fullname": "Micky Mellon",
21
"firstname": "Micky",
22
"lastname": "Mellon",
23
"nationality": "Scotland",
24
"birthdate": "18/03/1972",
25
"birthcountry": "Scotland",
26
"birthplace": "Paisley",
27
"image_path": "https://cdn.sportmonks.com/images/soccer/players/18/896498.png"
28
}
Copied!
Now, we can see that the coach of the visitor team is called Micky Mellon with coach id 896498.
See how flexible the API requests and responses can be? You request exactly what you need and the API will return exactly that.