Unleashing the potential of Sportmonks Football API with JSON

1. JSON

As mentioned earlier, JSON enables you to set up seamless communication between web applications and servers. So, why is it the go-to choice for many developers?

1.1 Why JSON?

According to Oracle, JSON stands out as a favoured data format among web developers, serving as a go-to choice for transmitting data between servers and web applications. It is as popular due to its ability to streamline data exchange across diverse technologies. Consider a scenario where a user initiates a purchase on a web platform; JSON steps in as the intermediary language. The user’s input is turned into JSON format and moved to the server. Upon processing, the server exchanges with a JSON-formatted response, seamlessly integrated and presented by the web application. This symbiotic relationship ensures swift, dynamic, and engaging web interactions, enhancing user experiences across the digital landscape. Picture this: a Java application effortlessly shares JSON data with a Python counterpart, while a JavaScript-powered mobile app communicates flawlessly with a PHP-powered server. All thanks to JSON’s language-agnostic nature.

Expanding beyond the realm of web development, JSON finds its place within applications and IT systems for efficient configuration management. Imagine JSON-formatted configuration files housing crucial details like database connections, API keys, and user preferences. By storing configuration data in JSON files, developers unlock a realm of simplicity and flexibility, enabling swift modifications to application settings sans intricate code alterations.

Okay, now you know why you should use JSON, so what holds you back? Let’s start using the Football API right away.

2. Authentication

Authentication is important for your application as it is essential to ensure secure access to the data. Everyone using the Football API has a unique token to validate their identity and authorise their requests.

2.1 Create your token

After registering at MySportmonks, you need to create your own API token. After that, you will be able to access the data in our API—as easy as you like. The data you have access to depends on your subscription. After changing subscriptions, you won’t have to create a new API token.

2.2 Authentication using JSON

You can pass your API token by passing ‘api_token’ in your request parameters like this:

https://api.sportmonks.com/api/v3/football/livescores?api_token=YOUR_TOKEN

You can authenticate using a request header as well. That should be done as discussed in our documentation page “Authentication“.

3.1 Your first request with JSON

Okay, now all of that is out of the way, we can start requesting data. So, what are you waiting for? Finding out which endpoints are available is important to start using the API as efficiently as possible. So, we will start with the “all-leagues” endpoint, as you will probably use this at the start of your journey anyway to understand all the leagues you have in your subscription and what IDs belong to them.

You can simply put this link in your browser, and you will see all leagues in your subscription. Remember to put in your API Token and delete the brackets around it.

https://api.sportmonks.com/v3/football/leagues?api_token=[YOUR_TOKEN]

3.2 The response

If you haven’t opted in for one of the plans, you will have access to the Free Plan. Which means your response should show other leagues than the one on the right side of your screen.

As you can see, the response is completely JSON formatted, making it easy to integrate into your application.

Upon receiving your request, you can access a list of available leagues. Would you like to explore each league’s ongoing season? Simply utilise the currentSeason parameter in the endpoint, and you’re all set!

The example response is on the right side of your screen. Remember that you will have other leagues when subscribed to a specific plan.

You can start building your other requests with all the IDs you have just discovered. We will show you an example in the next section.

{
{
  "data": [
    {
      "id": 2,
      "sport_id": 1,
      "country_id": 41,
      "name": "Champions League",
      "active": true,
      "short_code": "UEFA CL",
      "image_path": "https://cdn.sportmonks.com/images/soccer/leagues/2.png",
      "type": "league",
      "sub_type": "cup_international",
      "last_played_at": "2024-04-17 19:00:00",
      "category": 1,
      "has_jerseys": false
    },
    {
      "id": 5,
      "sport_id": 1,
      "country_id": 41,
      "name": "Europa League",
      "active": true,
      "short_code": "UEFA EL",
      "image_path": "https://cdn.sportmonks.com/images/soccer/leagues/5/5.png",
      "type": "league",
      "sub_type": "cup_international",
      "last_played_at": "2024-04-18 19:00:00",
      "category": 1,
      "has_jerseys": false
    },
    {
      "id": 8,
      "sport_id": 1,
      "country_id": 462,
      "name": "Premier League",
      "active": true,
      "short_code": "UK PL",
      "image_path": "https://cdn.sportmonks.com/images/soccer/leagues/8/8.png",
      "type": "league",
      "sub_type": "domestic",
      "last_played_at": "2024-04-28 15:30:00",
      "category": 1,
      "has_jerseys": false
    },
    {
      "id": 9,
      "sport_id": 1,
      "country_id": 462,
      "name": "Championship",
      "active": true,
      "short_code": "UK Champ",
      "image_path": "https://cdn.sportmonks.com/images/soccer/leagues/9/9.png",
      "type": "league",
      "sub_type": "domestic",
      "last_played_at": "2024-04-29 19:00:00",
      "category": 2,
      "has_jerseys": false
    },
    {
      "id": 12,
      "sport_id": 1,
      "country_id": 462,
      "name": "League One",
      "active": true,
      "short_code": "UK L1",
      "image_path": "https://cdn.sportmonks.com/images/soccer/leagues/12/12.png",
      "type": "league",
      "sub_type": "domestic",
      "last_played_at": "2024-04-27 11:30:00",
      "category": 2,
      "has_jerseys": false
    },
    {
      "id": 14,
      "sport_id": 1,
      "country_id": 462,
      "name": "League Two",
      "active": true,
      "short_code": "UK L2",
      "image_path": "https://cdn.sportmonks.com/images/soccer/leagues/14/14.png",
      "type": "league",
      "sub_type": "domestic",
      "last_played_at": "2024-04-27 14:00:00",
      "category": 2,
      "has_jerseys": false
    },
//and more!

4. Season and teams

We can determine which teams will be playing in specific seasons with the IDs we collected in the previous section. For this example, we will examine the 2023/2024 season from the Premier League.

To do so, we will use the Teams by Season ID endpoint. The JSON response will show all the teams in the particular season (ID) you are using. The specific ID for the 2023/2024 Premier League season is 21646.

https://api.sportmonks.com/v3/football/teams/seasons/21646?api_token=[YOUR_TOKEN]

This isn’t rocket science at all, is it? Of course, we will go a bit further. You have all your leagues and know how to get all the teams from specific seasons. You can find the players in those teams if you use the players.player include. To form the response precisely as you want, you can use filters and selecting fields.

{
  "data": [
    {
      "id": 19,
      "sport_id": 1,
      "country_id": 462,
      "venue_id": 204,
      "gender": "male",
      "name": "Arsenal",
      "short_code": "ARS",
      "image_path": "https://cdn.sportmonks.com/images/soccer/teams/19/19.png",
      "founded": 1886,
      "type": "domestic",
      "placeholder": false,
      "last_played_at": "2024-05-04 11:30:00",
      "players": [
        {
          "id": 633774,
          "transfer_id": 183831,
          "player_id": 61780,
          "team_id": 19,
          "position_id": 27,
          "detailed_position_id": 152,
          "start": "2023-01-20",
          "end": "2026-06-30",
          "captain": false,
          "jersey_number": 19,
          "player": {
            "id": 61780,
            "sport_id": 1,
            "country_id": 556,
            "nationality_id": 556,
            "city_id": null,
            "position_id": 27,
            "detailed_position_id": 152,
            "type_id": 26,
            "common_name": "L. Trossard",
            "firstname": "Leandro",
            "lastname": "Trossard",
            "name": "Leandro Trossard",
            "display_name": "Leandro Trossard",
            "image_path": "https://cdn.sportmonks.com/images/soccer/players/20/61780.png",
            "height": 172,
            "weight": 61,
            "date_of_birth": "1994-12-04",
            "gender": "male"
          }
        },
        {
          "id": 874920,
          "transfer_id": null,
          "player_id": 37676786,
          "team_id": 19,
          "position_id": 25,
          "detailed_position_id": null,
          "start": null,
          "end": null,
          "captain": false,
          "jersey_number": 79,
          "player": {
            "id": 37676786,
            "sport_id": 1,
            "country_id": 462,
            "nationality_id": 462,
            "city_id": null,
            "position_id": 25,
            "detailed_position_id": null,
            "type_id": null,
            "common_name": "A. Heaven",
            "firstname": "Ayden",
            "lastname": "Heaven",
            "name": "Ayden Heaven",
            "display_name": "A. Heaven",
            "image_path": "https://cdn.sportmonks.com/images/soccer/placeholder.png",
            "height": null,
            "weight": null,
            "date_of_birth": "2006-09-22",
            "gender": "male"
          }
        },
        {
          "id": 840512,
          "transfer_id": null,
          "player_id": 5329,
          "team_id": 19,
          "position_id": 27,
          "detailed_position_id": null,
          "start": null,
          "end": null,
          "captain": false,
          "jersey_number": 9,
          "player": {
            "id": 5329,
            "sport_id": 1,
            "country_id": 5,
            "nationality_id": 5,
            "city_id": null,
            "position_id": 27,
            "detailed_position_id": 151,
            "type_id": 27,
            "common_name": "G. de Jesus",
            "firstname": "Gabriel Fernando",
            "lastname": "de Jesus",
            "name": "Gabriel Fernando de Jesus",
            "display_name": "Gabriel Jesus",
            "image_path": "https://cdn.sportmonks.com/images/soccer/players/17/5329.png",
            "height": 175,
            "weight": 73,
            "date_of_birth": "1997-04-03",
            "gender": "male"
          }
        },
        {
          "id": 635736,
          "transfer_id": 184003,
          "player_id": 8403613,
          "team_id": 19,
          "position_id": 25,
          "detailed_position_id": 148,
          "start": "2023-01-23",
          "end": "2028-06-30",
          "captain": false,
          "jersey_number": 15,
          "player": {
            "id": 8403613,
            "sport_id": 1,
            "country_id": 2,
            "nationality_id": 2,
            "city_id": null,
            "position_id": 25,
            "detailed_position_id": 155,
            "type_id": 25,
            "common_name": "J. Kiwior",
            "firstname": "Jakub Piotr",
            "lastname": "Kiwior",
            "name": "Jakub Piotr Kiwior",
            "display_name": "Jakub Kiwior",
            "image_path": "https://cdn.sportmonks.com/images/soccer/players/29/8403613.png",
            "height": 189,
            "weight": null,
            "date_of_birth": "2000-02-15",
            "gender": "male"
          }
        },
        {
          "id": 2141,
          "transfer_id": 49023,
          "player_id": 3259,
          "team_id": 19,
          "position_id": 25,
          "detailed_position_id": 154,
          "start": "2021-07-30",
          "end": "2026-06-30",
          "captain": false,
          "jersey_number": 4,
          "player": {
            "id": 3259,
            "sport_id": 1,
            "country_id": 462,
            "nationality_id": 462,
            "city_id": 70548,
            "position_id": 25,
            "detailed_position_id": 154,
            "type_id": 25,
            "common_name": "B. White",
            "firstname": "Ben",
            "lastname": "White",
            "name": "Ben White",
            "display_name": "Ben White",
            "image_path": "https://cdn.sportmonks.com/images/soccer/players/27/3259.png",
            "height": 186,
            "weight": 78,
            "date_of_birth": "1997-10-08",
            "gender": "male"
          }
        },
        {
          "id": 2152,
          "transfer_id": 158134,
          "player_id": 1494446,
          "team_id": 19,
          "position_id": 26,
          "detailed_position_id": 150,
          "start": "2020-08-01",
          "end": "2026-06-30",
          "captain": false,
          "jersey_number": 10,
          "player": {
            "id": 1494446,
            "sport_id": 1,
            "country_id": 462,
            "nationality_id": 462,
            "city_id": 21232,
            "position_id": 26,
            "detailed_position_id": 150,
            "type_id": 26,
            "common_name": "E. Smith Rowe",
            "firstname": "Emile",
            "lastname": "Smith Rowe",
            "name": "Emile Smith Rowe",
            "display_name": "Emile Smith Rowe",
            "image_path": "https://cdn.sportmonks.com/images/soccer/players/14/1494446.png",
            "height": 182,
            "weight": null,
            "date_of_birth": "2000-07-28",
            "gender": "male"
          }
        },
        {
          "id": 2150,
          "transfer_id": 43423,
          "player_id": 186370,
          "team_id": 19,
          "position_id": 26,
          "detailed_position_id": 149,
          "start": "2020-10-05",
          "end": "2025-06-30",
          "captain": false,
          "jersey_number": 5,
          "player": {
            "id": 186370,
            "sport_id": 1,
            "country_id": 468,
            "nationality_id": 468,
            "city_id": null,
            "position_id": 26,
            "detailed_position_id": 149,
            "type_id": 26,
            "common_name": "T. Partey",
            "firstname": "Thomas Teye",
            "lastname": "Partey",
            "name": "Thomas Teye Partey",
            "display_name": "Thomas Partey",
            "image_path": "https://cdn.sportmonks.com/images/soccer/players/2/186370.png",
            "height": 185,
            "weight": 77,
            "date_of_birth": "1993-06-13",
            "gender": "male"
          }
        },

Okay, this is all very cool. But you still miss one of the most important things in Football Data. How do you get player statistics? Let’s find out in the next chapter.

5. Player season stats

Now, we will show you the real magic. Again, there are multiple options for receiving the data you need. However, we recommend the Get Team Squad by Team ID endpoint (for current-season team squads) or the Squad by Team and Season ID endpoint (for historical team squads).

Let’s say you want to see the players from Liverpool (Team ID 8) with their current season stats.

https://api.sportmonks.com/v3/football/squads/teams/8?api_token=[YOUR_TOKEN]&include=player.statistics.details&filters=playerStatisticSeasons:21646

The other endpoint would look like this. We will look at the 2022/2023 season for this endpoint (different season ID).

https://api.sportmonks.com/v3/football/squads/seasons/19734/teams/19?api_token=[YOUR_TOKEN]&include=player;details.type

Our API can do way more. You can start playing around with the API or look at the documentation to find all this information.

{
  "data": [
    {
      "id": 32901,
      "transfer_id": 1615,
      "player_id": 241036,
      "team_id": 8,
      "position_id": 27,
      "detailed_position_id": 152,
      "start": "2022-01-30",
      "end": "2027-06-30",
      "captain": false,
      "jersey_number": 7,
      "player": {
        "id": 241036,
        "sport_id": 1,
        "country_id": 353,
        "nationality_id": 353,
        "city_id": 6818,
        "position_id": 27,
        "detailed_position_id": 152,
        "type_id": 26,
        "common_name": "L. Díaz Marulanda",
        "firstname": "Luis Fernando",
        "lastname": "Díaz Marulanda",
        "name": "Luis Fernando Díaz Marulanda",
        "display_name": "Luis  Díaz",
        "image_path": "https://cdn.sportmonks.com/images/soccer/players/12/241036.png",
        "height": 180,
        "weight": null,
        "date_of_birth": "1997-01-13",
        "gender": "male",
        "statistics": [
          {
            "id": 483841199,
            "player_id": 241036,
            "team_id": 8,
            "season_id": 21646,
            "has_values": true,
            "position_id": 27,
            "jersey_number": 7,
            "details": [
              {
                "id": 34125721,
                "player_statistic_id": 483841199,
                "type_id": 41,
                "value": {
                  "total": 30
                }
              },
              {
                "id": 31622758,
                "player_statistic_id": 483841199,
                "type_id": 42,
                "value": {
                  "total": 88
                }
              },
              {
                "id": 34152907,
                "player_statistic_id": 483841199,
                "type_id": 47,
                "value": {
                  "total": 0,
                  "won": 1,
                  "scored": 0,
                  "committed": 0,
                  "saved": 0,
                  "missed": 0
                }
              },
              {
                "id": 31622678,
                "player_statistic_id": 483841199,
                "type_id": 51,
                "value": {
                  "total": 15
                }
              },
              {
                "id": 31622598,
                "player_statistic_id": 483841199,
                "type_id": 52,
                "value": {
                  "total": 8,
                  "goals": 8,
                  "penalties": 0
                }
              },
              {
                "id": 31695316,
                "player_statistic_id": 483841199,
                "type_id": 56,
                "value": {
                  "total": 45
                }
              },
              {
                "id": 31622764,
                "player_statistic_id": 483841199,
                "type_id": 58,
                "value": {
                  "total": 28
                }
              },
              {
                "id": 31622793,
                "player_statistic_id": 483841199,
                "type_id": 59,
                "value": {
                  "in": 5,
                  "out": 18
                }
              },
              {
                "id": 36313024,
                "player_statistic_id": 483841199,
                "type_id": 64,
                "value": {
                  "total": 2
                }
              },
              {
                "id": 31622804,
                "player_statistic_id": 483841199,
                "type_id": 78,
                "value": {
                  "total": 30
                }
              },
              {
                "id": 34139451,
                "player_statistic_id": 483841199,
                "type_id": 79,
                "value": {
                  "total": 5
                }
              },
              {
                "id": 31622688,
                "player_statistic_id": 483841199,
                "type_id": 80,
                "value": {
                  "total": 932
                }
              },
              {
                "id": 34054157,
                "player_statistic_id": 483841199,
                "type_id": 84,
                "value": {
                  "total": 3,
                  "home": 1,
                  "away": 2
                }
              },
              {
                "id": 31622777,
                "player_statistic_id": 483841199,
                "type_id": 86,
                "value": {
                  "total": 30
                }
              },
              {
                "id": 33032130,
                "player_statistic_id": 483841199,
                "type_id": 87,
                "value": {
                  "total": 3
                }
              },
              {
                "id": 31622621,
                "player_statistic_id": 483841199,
                "type_id": 88,
                "value": {
                  "total": 31
                }
              },
              {
                "id": 31622550,
                "player_statistic_id": 483841199,
                "type_id": 94,
                "value": {
                  "total": 69
                }
              },
              {
                "id": 31695318,
                "player_statistic_id": 483841199,
                "type_id": 96,
                "value": {
                  "total": 38
                }
              },
              {
                "id": 31695377,
                "player_statistic_id": 483841199,
                "type_id": 98,
                "value": {
                  "total": 25
                }
              },
              {
                "id": 31695288,
                "player_statistic_id": 483841199,
                "type_id": 99,
                "value": {
                  "total": 6
                }
              },
              {
                "id": 31879006,
                "player_statistic_id": 483841199,
                "type_id": 100,
                "value": {
                  "total": 3
                }
              },
              {
                "id": 34040253,
                "player_statistic_id": 483841199,
                "type_id": 101,
                "value": {
                  "total": 7
                }
              },
              {
                "id": 31622574,
                "player_statistic_id": 483841199,
                "type_id": 105,
                "value": {
                  "total": 384
                }
              },
              {
                "id": 31622577,
                "player_statistic_id": 483841199,
                "type_id": 106,
                "value": {
                  "total": 153
                }
              },
              {
                "id": 31695294,
                "player_statistic_id": 483841199,
                "type_id": 107,
                "value": {
                  "total": 26
                }
              },
              {
                "id": 31622556,
                "player_statistic_id": 483841199,
                "type_id": 108,
                "value": {
                  "total": 112
                }
              },
              {
                "id": 33032127,
                "player_statistic_id": 483841199,
                "type_id": 109,
                "value": {
                  "total": 55
                }
              },
              {
                "id": 31622565,
                "player_statistic_id": 483841199,
                "type_id": 110,
                "value": {
                  "total": 21
                }
              },
              {
                "id": 31622522,
                "player_statistic_id": 483841199,
                "type_id": 116,
                "value": {
                  "total": 793
                }
              },
              {
                "id": 31622634,
                "player_statistic_id": 483841199,
                "type_id": 117,
                "value": {
                  "total": 57
                }
              },
              {
                "id": 31622713,
                "player_statistic_id": 483841199,
                "type_id": 118,
                "value": {
                  "average": 7.34,
                  "highest": 9.08,
                  "lowest": 6.32
                }
              },
              {
                "id": 31622669,
                "player_statistic_id": 483841199,
                "type_id": 119,
                "value": {
                  "total": 2423
                }
              },
              {
                "id": 31622653,
                "player_statistic_id": 483841199,
                "type_id": 122,
                "value": {
                  "total": 53
                }
              },
              {
                "id": 31622663,
                "player_statistic_id": 483841199,
                "type_id": 123,
                "value": {
                  "total": 43
                }
              },
              {
                "id": 36313026,
                "player_statistic_id": 483841199,
                "type_id": 124,
                "value": {
                  "total": 1
                }
              },
              {
                "id": 31622534,
                "player_statistic_id": 483841199,
                "type_id": 321,
                "value": {
                  "total": 34
                }
              },
              {
                "id": 31622644,
                "player_statistic_id": 483841199,
                "type_id": 322,
                "value": {
                  "total": 29
                }
              },
              {
                "id": 33107167,
                "player_statistic_id": 483841199,
                "type_id": 323,
                "value": {
                  "total": 5
                }
              },
              {
                "id": 33107168,
                "player_statistic_id": 483841199,
                "type_id": 580,
                "value": {
                  "total": 5
                }
              },
              {
                "id": 31622542,
                "player_statistic_id": 483841199,
                "type_id": 581,
                "value": {
                  "total": 11
                }
              },
              {
                "id": 31622514,
                "player_statistic_id": 483841199,
                "type_id": 1584,
                "value": {
                  "total": 85.09
                }
              },
              {
                "id": 36146030,
                "player_statistic_id": 483841199,
                "type_id": 9676,
                "value": {
                  "average ppg per season": "0.24"
                }
              }
            ]
          }
        ]
      }
    },

6. Conclusion

This guide explains some basic principles for using our JSON Football API. Once you know how to use the endpoints discussed above, you will surely be able to unlock the power of Sportmonks’ API and take your application to the next level.

The API is completely JSON formatted. However, if you would like to use the Football API while using PHP, Python or any other language, that is certainly possible. It is also possible to use our API with Postman.

We have covered the basics, but these are essential for optimising the performance of your application and getting the most out of the Football API.

Remember, we were only able to show you a few endpoints. There are a boundless number of other endpoints. Many ways lead to Rome, so you can find other ways to get your desired response. We offer flexibility to our customers by having the responses in JSON and offering as many endpoints as we do. Besides that, the include, filtering and selecting fields options allow you to shape the API response to your liking.

Another big plus is that Sportmonks keeps innovating, and the API will continuously expand with all kinds of new functionalities. So, keep an eye out for that as well.