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

https://soccer.sportmonks.com/api/v2.0/?api_token={API_TOKEN}

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:

https://soccer.sportmonks.com/api/v2.0/fixtures/date/{Date}?api_token={API_TOKEN}

The date has to be in the format of YYYY-MM-DD. In this example, we’ll take the date of 2020-09-26.

https://soccer.sportmonks.com/api/v2.0/fixtures/date/2020-09-26?api_token={API_TOKEN}

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.

{
    "data": [
        {
            "id": 16475331,
            "league_id": 501,
            "season_id": 17141,
            "stage_id": 77447501,
            "round_id": 194976,
            "group_id": null,
            "aggregate_id": null,
            "venue_id": 14509,
            "referee_id": 15815,
            "localteam_id": 338,
            "visitorteam_id": 282,
            "winner_team_id": null,

You can check out our fixtures & livescores tutorials if you want more detailed information.

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.

https://soccer.sportmonks.com/api/v2.0/fixtures/date/2020-09-26?api_token={API_TOKEN}

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:

https://soccer.sportmonks.com/api/v2.0/fixtures/date/2020-09-26?api_token={API_TOKEN}&include=localTeam,visitorTeam

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.

 "localTeam": {
                "data": {
                    "id": 338,
                    "legacy_id": 693,
                    "name": "Hamilton Academical",
                    "short_code": "HMA",
                    "twitter": null,
                    "country_id": 1161,
                    "national_team": false,
                    "founded": 1874,
                    "logo_path": "https://cdn.sportmonks.com/images//soccer/teams/18/338.png",
                    "venue_id": 288196,
                    "current_season_id": 17141
                }
            },
            "visitorTeam": {
                "data": {
                    "id": 282,
                    "legacy_id": 692,
                    "name": "Dundee United",
                    "short_code": "DUD",
                    "twitter": null,
                    "country_id": 1161,
                    "national_team": false,
                    "founded": 1909,
                    "logo_path": "https://cdn.sportmonks.com/images//soccer/teams/26/282.png",
                    "venue_id": 8947,
                    "current_season_id": 17141
                }

You can check out our includes tutorial if you want more detailed information.

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:

https://soccer.sportmonks.com/api/v2.0/fixtures/date/2020-09-26?api_token={API_TOKEN}&include=localTeam,visitorTeam.coach

"visitorTeam": {
                "data": {
                    "id": 282,
                    "legacy_id": 692,
                    "name": "Dundee United",
                    "short_code": "DUD",
                    "twitter": null,
                    "country_id": 1161,
                    "national_team": false,
                    "founded": 1909,
                    "logo_path": "https://cdn.sportmonks.com/images//soccer/teams/26/282.png",
                    "venue_id": 8947,
                    "current_season_id": 17141,
                    "coach": {
                        "data": {
                            "coach_id": 896498,
                            "team_id": 201,
                            "country_id": 1161,
                            "common_name": "M. Mellon",
                            "fullname": "Micky Mellon",
                            "firstname": "Micky",
                            "lastname": "Mellon",
                            "nationality": "Scotland",
                            "birthdate": "18/03/1972",
                            "birthcountry": "Scotland",
                            "birthplace": "Paisley",
                            "image_path": "https://cdn.sportmonks.com/images/soccer/players/18/896498.png"
                        }

Now, we can see that the coach of the visitor team is called Micky Mellon with coach id 896498.

You can check out our nested includes tutorial if you want more detailed information.

See how flexible the API requests and responses can be? You request exactly what you need and the API will return exactly that.