Today, we’re happy to announce that Sportmonks has officially released API 3.0!
The new version uses an entirely new back-end structure to ensure a higher level of data reliability and performance. We’ve written this blog to help you understand how to adopt all the latest changes, improve the quality of your applications and streamline your development experience. Here’s a quick overview of what to expect from API 3.0:
We encourage you to adopt the new version of our API so that you can benefit from various new features and improved data quality. Future innovations will be published on API 3.0 only, so staying on API 2.0 is not recommended.
We have kept your wishes and needs in mind and worked very hard to fulfil these whilst building the API. So without further ado, let’s dive straight in!
API 3.0 brings all kinds of new data features. Let’s take a look at some of the new data features:
– Offside events for major leagues
– Detailed player positions
– Shots on/off target events for major leagues
– Placeholder games available
– Ball coordinates (semi-live)
– Pressure Index
– Forecast weather report
– More predictions
– Predictive line-up (Beta)
– Coach and referee statistics
– Period statistics
– More statistics in general
Let’s take a closer look at some of our new features.
Detailed position
Detailed positions are something many of you have been requesting. In API 2.0, you can only see if a player is a keeper, defender, midfielder, or attacker on a player profile. In API 3.0, you can find out if a player is a left-back, centre-back, or right-back (obviously, this also goes for midfielders and attackers). So, you know at which position a specific player is mainly playing. Of course in the lineup records, you can also find more specific information on the player position per fixture.
Placeholders
In API 2.0, only the World Cup and European Championship had placeholders for tournaments. Now we have the placeholder teams available for all tournaments with pre-set routes like the World Cup. Therefore, if team 1 of group A plays versus team 2 of group B, after the group stage, we will have this matchup filled with placeholders. The correct team will replace the placeholders after we know which team will play in the next round. This feature is perfect for building Cup schedules and overviews.
Ball coordinates (semi-live)
From now on, we will provide the ball’s coordinates on the pitch. Knowing the location of the ball can be helpful for your customers. It adds another dimension to following the most exciting game in the world. The Ball coordinates feature will be automatically added to plans with advanced data features.
Pressure index
Another new data feature is the pressure index. We calculate the pressure teams lay on each other during a fixture. The pressure index is calculated based on various statistics, like ball possession, dangerous attacks, corners, shots, and more! The pressure index feature will be available as an optional add-on to your subscription.
Predictive line-ups
Another feature that has been asked for very heavily. You wanted to be able to show the predicted line-ups, and now we deliver. The predictive line-ups are here to do exactly that. You will be able to ensure your customers are ready for the matchup.
New and more statistics
Yes, we offer way more statistics now. Next to more player, team, season, and match statistics, we have entirely new statistics. Two of them are statistics for coaches and referees. You can expect many more statistics in 2023 in API 3.0. Let us know which ones you would like to see!
Again, we have listened to your wishes. You wanted new endpoints to make it even easier to get specific data. Therefore, we implemented an extensive set of new endpoints.
We created endpoints for transfers, referees and schedules. Besides that, all entities with a name field are extended and have an endpoint to search by names. Almost every entity has additional endpoints, including “GET All Endpoints”. The “all” endpoints are built to help you with initial data loads and to keep your database in SYNC. Check them out!
Your subscription
Furthermore, we have created endpoints around your subscription. From now on, you will be able to:
Core and odds
It’s important to note that Core and odds are no longer sport specific. Both have documentation and are related to all sports released on API 3.0.
League priority
Again, this is a feature you have been asking about a lot in recent months, so here it is. You can now prioritise your responses based on your league priority. You can order the leagues how you want. Go to MySportmonks to prioritise the leagues that pique your interest.
We are proud to tell you we cover 99 statistics due to our new API 3.0. And because of the flexibility of our new API, we can add even more very soon.
The number of statistics made it necessary to distribute them over our standard and advanced packages.
The new distribution means that some statistics will be included in our advanced package and no longer in our standard packages.
At this point, the standard package will have 42 stats, while the other 57 are included in our advanced data features. A list is created to display which stats are included in the standard and advanced packages so you can opt for the statistics you’re interested in while choosing your plan. You can find this list on our data features page or by clicking the button below.
If you are currently subscribed to a API 2.0 subscription, you will have access to advanced stats in your API 3.0 subscription.
Filters are improved in API 3.0 to give even more possibilities to get the data in your preferred way. Each endpoint has two types of filters: static and dynamic filters. You can combine any dynamic filter with any static filter or use a multitude.
Let’s take a look at an example.
Imagine you’re interested in the match events of the World Cup final.
Your request would look like this:
https://api.sportmonks.com/v3/football/fixtures/18452325?api_token=YOUR_TOKEN&include=events
The response
{
"data": {
"id": 18452325,
"sport_id": 1,
"league_id": 732,
"season_id": 18017,
"stage_id": 77452381,
"group_id": null,
"aggregate_id": null,
"round_id": null,
"state_id": 8,
"venue_id": 343341,
"name": "Argentina vs France",
"starting_at": "2022-12-18 15:00:00",
"result_info": "Argentina won after penalties.",
"leg": "1/1",
"details": null,
"length": 90,
"placeholder": false,
"last_processed_at": "2023-03-02 17:50:41",
"has_odds": true,
"starting_at_timestamp": 1671375600,
"events": [
{
"id": 71140989,
"fixture_id": 18452325,
"period_id": 4539357,
"participant_id": 18644,
"type_id": 16,
"section": "event",
"player_id": 184798,
"related_player_id": null,
"player_name": "Lionel Messi",
"related_player_name": null,
"result": "1-0",
"info": null,
"addition": "1st Goal",
"minute": 23,
"extra_minute": null,
"injured": null,
"on_bench": false,
"coach_id": null,
"sub_type_id": 1522
},
{
"id": 71141553,
"fixture_id": 18452325,
"period_id": 4539357,
"participant_id": 18644,
"type_id": 14,
"section": "event",
"player_id": 4105,
"related_player_id": 216612,
"player_name": "Ángel Di María ",
"related_player_name": "A. Mac Allister",
"result": "2-0",
"info": null,
"addition": "2nd Goal",
"minute": 36,
"extra_minute": null,
"injured": null,
"on_bench": false,
"coach_id": null,
"sub_type_id": 1522
},
{
"id": 71145170,
"fixture_id": 18452325,
"period_id": 4539357,
"participant_id": 18647,
"type_id": 18,
"section": "event",
"player_id": 432872,
"related_player_id": 32403,
"player_name": "R. Kolo Muani",
"related_player_name": "Ousmane Dembélé",
"result": null,
"info": null,
"addition": null,
"minute": 41,
"extra_minute": null,
"injured": false,
"on_bench": false,
"coach_id": null,
"sub_type_id": 1523
},
{
"id": 71145474,
"fixture_id": 18452325,
"period_id": 4539357,
"participant_id": 18647,
"type_id": 18,
"section": "event",
"player_id": 99000,
"related_player_id": 798,
"player_name": "Marcus Thuram",
"related_player_name": "Olivier Giroud",
"result": null,
"info": null,
"addition": null,
"minute": 41,
"extra_minute": null,
"injured": false,
"on_bench": false,
"coach_id": null,
"sub_type_id": 1523
},
{
"id": 71149608,
"fixture_id": 18452325,
"period_id": 4539396,
"participant_id": 18644,
"type_id": 18,
"section": "event",
"player_id": 212976,
"related_player_id": 4105,
"player_name": "Marcos Acuña",
"related_player_name": "Ángel Di María ",
"result": null,
"info": null,
"addition": null,
"minute": 64,
"extra_minute": null,
"injured": false,
"on_bench": false,
"coach_id": null,
"sub_type_id": 1523
},
{
"id": 71149766,
"fixture_id": 18452325,
"period_id": 4539396,
"participant_id": 18647,
"type_id": 14,
"section": "event",
"player_id": 96611,
"related_player_id": 99000,
"player_name": "Kylian Mbappé",
"related_player_name": "Marcus Thuram",
"result": "2-2",
"info": null,
"addition": "4th Goal",
"minute": 81,
"extra_minute": null,
"injured": null,
"on_bench": false,
"coach_id": null,
"sub_type_id": 1522
},
//and more!
As you can see in the response, you will receive all match events. But what if you’re only interested in a specific event like goals, cards or substitutions? You can filter on the specific data you’re interested in. For this example, we are only interested in the substitutions and goals. To filter your request, you need to:
In our case, this will result in the following steps:
This results in the filter: evenTypes:18,14
https://api.sportmonks.com/v3/football/fixtures/18452325?api_token=YOUR_TOKEN&include=events&filters=eventTypes:18,14
Please check our request options page for more detailed information and helpful examples.
API 3.0 introduces the possibility of requesting specific fields on entities. This possibility is useful when you only use particular fields in an API response. The advantage of selecting specific fields is that it decreases the response times and size, especially in large responses. In addition to reducing response time, the response size can also be drastically reduced. Let’s take a look at a quick example together.
One of our new additions to API 3.0 is a name field on the fixtures. The name field contains a textual representation of the participants playing the fixture. Without selecting a specific field, the API request and response would look like this:
Request
https://api.sportmonks.com/v3/football/fixtures/18452325?api_token=YOUR_TOKEN
Response
{
"data": {
"id": 18452325,
"sport_id": 1,
"league_id": 732,
"season_id": 18017,
"stage_id": 77452381,
"group_id": null,
"aggregate_id": null,
"round_id": null,
"state_id": 8,
"venue_id": 343341,
"name": "Argentina vs France",
"starting_at": "2022-12-18 15:00:00",
"result_info": "Argentina won after penalties.",
"leg": "1/1",
"details": null,
"length": 90,
"placeholder": false,
"last_processed_at": "2023-03-02 17:50:41",
"has_odds": true,
"starting_at_timestamp": 1671375600
},
As you can see, the API response is rather large if you’re only interested in the fixture’s name. Let’s select that API field to reduce the response length and size.
We’re using the fixtures endpoint. This means we can select all the fields of the fixtures entity.
You can add &select={specific fields on the base entity}.
In our example, this would result in the below API request and response:
Request
https://api.sportmonks.com/v3/football/fixtures/18452325?api_token=YOUR_TOKEN&select=name
Response
{
"data": {
"name": "Argentina vs France",
"id": 18452325,
"sport_id": 1,
"round_id": null,
"stage_id": 77452381,
"group_id": null,
"aggregate_id": null,
"league_id": 732,
"season_id": 18017,
"venue_id": 343341,
"state_id": 8,
"starting_at_timestamp": null
},
Quite convenient, isn’t it? Please check our documentation pages for more examples and information.
Along with our API update, our documentation pages are also updated. With all these changes, that was essential. So, let’s find out where you can find the information you need.
Football
As mentioned before, there is a new set-up in our API. Football, Core and Odds are different domains. You can visit our Football domain for all information about our Football API.
Core
One of the other domains is Core. All information about continents, countries, regions, cities, types and filters can be found here. Also, the endpoints showing your subscription information can be found in Core.
Odds
The Odds domain shows information about all endpoints related to odds. Like pre-match odds, inplay odds, bookmakers and markets.
Changelog
We always seek ways to expand our coverage and offer new features. We closely monitor our changelog to keep you updated about new features and changes to the latest version of our API.
Entities
The new documentation delivers all information about entities as well. You will find field descriptions, usable includes and filters and more at the chapter entities.
Tutorials
We’ve written some well-explained tutorials to give you a head start on how to use our API. First, we describe the basics, and later, in the articles, we explain how to make more advanced requests.
How-to guides
Our how-to guides explain how to use our API to reach specific goals. For example, if you want to create a livescore page, team page or standing page. We even made pages to help you configure widgets and create custom plans. Please remember that you are always free to contact us if you still have questions.
Want to get started right away? Start- now
We understand a lot is going on here, and we realize you will need time to integrate this new version into your application. That is why current users will keep their access to API 2.0 till mid 2024.
Make sure to integrate API 3.0 as soon as possible and make use of all the new features the Football API has to offer.