📄Changelog
Since the release of API3 and onwards, we will list any additions and changes made in the API on this page, in chronological order (YYYY-MM-DD format)
Last updated
Was this helpful?
2025-08-19
We’ve expanded match facts to include more granular statistics and standardised naming across categories. Since we are still in the beta phase, this change only applies to the upcoming matches.
Category h2h
Added:
MATCH_FACT_LAST_5_{STAT},MATCH_FACT_LAST_10_{STAT},MATCH_FACT_LAST_15_{STAT},MATCH_FACT_LAST_25_{STAT}Unchanged: existing
MATCH_FACT_{STAT}types (which still refer to all historical H2H matches between the teams)
Category overall
Previously: facts for the last 10 matches were supplied as
MATCH_FACT_{STAT}(e.g.MATCH_FACT_GOALS)Now: supplied as
MATCH_FACT_LAST_10_{STAT}(e.g.MATCH_FACT_LAST_10_GOALS)
Breaking change: the old MATCH_FACT_{STAT} is no longer supported in the overall category
Affected stats
The following {STAT} values are affected in both categories:
WINDRAWLOSSCLEANSHEETGOALSGOALS_CONCEDEDCORNERSREDCARDSYELLOWCARDSYELLOWRED_CARDSSHOTS_TOTALSHOTS_ON_TARGETFIRST_TO_SCOREGOAL_LINEBTTSWINNING_MARGINCARDS_COUNTGOAL_TIMINGSCARDS_COUNT_IN_MATCH
2025-06-30
We've introduced a new field, rescinded, to the Event entity. This field provides a boolean indicator for card events: true if the referee has rescinded the card or false if the card still counts. For other events (or historical card events where this information is not available yet), the field will be null.
{
"id": 149899270,
"fixture_id": 19134999,
"period_id": 6007175,
"participant_id": 52,
"type_id": 20,
"section": "event",
"player_id": 11298616,
"related_player_id": null,
"player_name": "Evanilson",
"related_player_name": null,
"result": null,
"info": "Foul",
"addition": "1st Redcard",
"minute": 70,
"extra_minute": null,
"injured": null,
"on_bench": false,
"coach_id": null,
"sub_type_id": null,
"detailed_period_id": 6007175,
"rescinded": true, <- Rescinded card
"sort_order": 1
}2025-03-10
Two new filters have been added to the API for enhanced flexibility and customization:
HavingPremiumOdds filter Allows users to filter out any fixtures not having premium odds available. Similar to the havingOdds filter for out default odds field. The filter can be applied on fixture entities.
api.sportmonks.com/v3/football/fixtures/date/2025-03-10?filters=havingPremiumOdds&api_token=TOKENGender filter Enables users to filter teams or players based on a specific gender (
male,female, ornull). If a player's gender is (yet) unknown, it is assigned a default value ofnull.
api.sportmonks.com/v3/football/teams?filters=genders:female&api_token=TOKEN2025-01-22
With the release of our new data-processing logic, we’ve introduced new types to better distinguish between extra time periods and their individual halves.
Previously, there was only a single period type for extra time: ET (type_id: 3). Now, extra time has been separated into two distinct types:
ET_1ST_HALF (type_id: 5314)
ET_2ND_HALF (type_id: 39).
To take advantage of these improvements, a new API include called detailedPeriods has been added. This include provides detailed information about periods, including the separation of extra time into its two halves.
In addition, events now include a detailed_period_id, which points to the corresponding detailedPeriod.
We strongly encourage all users to adopt this new structure to ensure greater consistency and accuracy in your applications. In the near future, we will make every effort to back populate historical fixtures with these detailed periods, to provide a more seamless experience with periods.
"detailedperiods": [
{
"id": 5811911,
"fixture_id": 19353646,
"type_id": 1,
"started": 1736884878,
"ended": 1736887852,
"counts_from": 0,
"ticking": false,
"sort_order": 1,
"description": "1st-half",
"time_added": 2,
"period_length": 45,
"minutes": 49,
"seconds": 34,
"has_timer": false
},
{
"id": 5812022,
"fixture_id": 19353646,
"type_id": 2,
"started": 1736888773,
"ended": 1736891833,
"counts_from": 45,
"ticking": false,
"sort_order": 2,
"description": "2nd-half",
"time_added": 6,
"period_length": 45,
"minutes": 96,
"seconds": 0,
"has_timer": false
},
{
"id": 5813446,
"fixture_id": 19353646,
"type_id": 39,
"started": 1736893340,
"ended": 1736894412,
"counts_from": 105,
"ticking": false,
"sort_order": 4,
"description": "extra-time-2nd-half",
"time_added": 1,
"period_length": 15,
"minutes": 122,
"seconds": 52,
"has_timer": false
},
{
"id": 5813445,
"fixture_id": 19353646,
"type_id": 5314,
"started": 1736888773,
"ended": 1736889673,
"counts_from": 90,
"ticking": false,
"sort_order": 3,
"description": "extra-time-1st-half",
"time_added": null,
"period_length": 15,
"minutes": 105,
"seconds": 0,
"has_timer": false
}
],2024-11-04
We've introduced a new metadata type, Prediction Status, to the Fixture entity. This metadata provides an indicator named predictable to indicate if the prediction model could accurately make fixture predictions.
If the model can't make accurate fixture predictions, the value of predictable will be false, and there will be no predictions available for that fixture.
// https://api.sportmonks.com/v3/football/fixtures/19134873?include=metadata.type
"metadata": [
// ...
{
"id": 6882438,
"metadatable_id": 19134873,
"type_id": 37072,
"value_type": "object",
"values": {
"predictable": true
},
"type": {
"id": 37072,
"name": "Prediction Status",
"code": "prediction-status",
"developer_name": "PREDICTION_STATUS",
"model_type": "metadata",
"stat_group": null
}
}
]2024-09-30
A new include call rankings has been added to the API. You may use this include on a Team to get information about the coefficient rankings for the desired team. We continue to expand our coverage regarding these rankings.
// https://api.sportmonks.com/v3/football/teams/8?include=rankings
"rankings": [
{
"id": 10,
"position": 4,
"participant_id": 8,
"points": 98000,
"sport_id": 1,
"type": "UEFA"
}
]2024-09-10
We've introduced a new field, sort_order, to the Event entity. This field provides a numerical ranking system to determine the chronological order of events within a specific type.
{
id: 120221102,
fixture_id: 19296203,
period_id: 5606524,
participant_id: 8,
type_id: 14,
section: "event",
player_id: 1743,
related_player_id: 84627,
player_name: "Virgil van Dijk",
related_player_name: "Konstantinos Tsimikas",
result: "1-2",
info: "Header",
addition: "3rd Goal",
minute: 41,
extra_minute: null,
injured: null,
on_bench: false,
coach_id: null,
sub_type_id: null
sort_order: 3 <- Assigned per type_id
},By assigning a unique sort order to each event within a type, users can more easily organize and display events in a sequential manner based on their occurrence. This feature allows for a more intuitive and efficient way to identify, browse and filter events.
2024-08-11
We're excited to announce new enhancements to our xG statistics, now available at the season level!
For both players and teams, you can now track their xG Over/Under performance throughout the entire season. This feature reveals how teams and players are actually performing compared to their expected goals (xG) 📊
Additionally, we've introduced the Expected Points table to our standings details. This new feature lets you compare a team's overall performance against their expected points, offering deeper insights into their season 👀 These new features are available for all of our customers having an xG standard or advanced package in their subscription 🔥⚽
2024-05-12
We're excited to announce the launch of Expected Goals (xG) metrics in the Sportmonks API! With the addition of xG data, users can now access valuable insights into goal-scoring probabilities, enhancing their football analysis and decision-making processes.
What's New?
xG Types: Explore detailed Expected Goals (xG) metrics, including Expected Goals (xG) and Expected Goals on Target (xGoT), for teams and players participating in football matches.
New Endpoints: Discover new endpoints, such as
v3/football/expected/fixturesandv3/football/expected/lineups, specifically designed to retrieve xG data per team or player lineup.
2024-04-05
Added new statistics types for teams on seasonal level: Card Per Foul, Shot On Target Percentage, Shot Conversion Rate, Penalty Conversion Rate, Most Injured Players, Most Substituted Players, Appearing Players, Average Points Per Game, Players Footing, Amount Of Foreigners, Average Player Age, and Average Player Height.
2024-03-21
Periods now show the elapsed minute and seconds even though a period is no longer ticking.
2024-02-26
Introducing the ability to perform custom sorting on Sportmonks API3 endpoints! With this enhancement, users can now include the
sortByparameter to sort base entities in ascending or descending order. The feature supports sorting on fields likestarting_atandnamefor fixtures, providing users with greater flexibility in organising and retrieving data.You can find more information on the dedicated sorting page.
2023-11-27
An endpoint to retrieve extended squad details has been added. This endpoint shows all players that were active in the current seasons for the team. If a player is no longer part of the squad or is currently a youth team player, the in_squad field is marked false.
Periods now contain a has_timer attribute. It marks whether we have detailed timer information for minutes and seconds attributes available.
Minor updates and optimisations to our back-end infrastructure.
2023-11-13
An endpoint that lists all the supported timezones has been added.
Passing your preferred time zone now also has direct effect on the query results on the League By Date endpoint.
2023-10-30
Due to a deviation in the aggregation of API3 request logs, we have cleared the tables records and added a fix for the behaviour. The API usage endpoint now returns the correct results again.
2023-09-21
A new event type has been implemented which tracks VAR checks related to cards. From today onwards all VAR events that are related to cards are covered under the VAR_CARD event type.
2023-09-13
An endpoint for insights into your API usage has been added. This endpoint will return your usage aggregated per endpoint per 5 minutes. You may for example use this endpoint to build your own monitoring dashboards, or to gain insights into how you can optimize your traffic to our API by spreading your usage. 📊💻
2023-09-06
Both Referee and Coach entities now offer the possibility to add the latest include. The include providers their latest fixtures records from the past 6 months.
2023-09-04
When available, a code field has been added to the API error response, these errors include a link to our documentation pages where the errors are explained more briefly. The code corresponds to one of the entries in the listed table.
When using the statistics include on a Season, using the nested Type include caused the original type field for the object to be overridden. To prevent this behaviour from happening, the relational Type object will now be available under the statistic_type attribute.
Type object now available under statistic_type attribute.
2023-08-15
TV station BT Sport has been renamed to TNT Sports due to rebranding. (affecting ID 46 and 860). TNT Sports 2, 3, 4 are newly added under ID 928, 929, 930.
2023-07-18
Filtering on id's on "All Endpoints" has now been added. You can use it to only request the entities of which the id is one of the given values. You need pass the name of the desired entity to apply the filters on. See the examples below for reference: https://api.sportmonks.com/v3/football/players?api_token=TOKEN&filters=playerIds:1,2,3,4,5 https://api.sportmonks.com/v3/football/leagues?api_token=TOKEN&filters=leagueIds:2,5,8
We have added the possibility to filter on active seasons when requesting statistics. You can pass the currentSeasons filter to leverage this functionality, make sure to pass the desired Entity to apply the filter on as well, check the example below for reference, this will only return. you statistics for current / active seasons that belong to players in the response: https://api.sportmonks.com/v3/football/players?api_token=TOKEN&include=statistics&filters=currentSeasons:playerStatistic
An is_captain indicator has been added for Squads. Showing true if the player is currently the default captain for the regarding squad.
Using filters that allow you to pass id's, now support a maximum of 50 records. This reflects the maximums (per_page) we allow on default paginated endpoints.
2023-06-08
Endpoints for retrieving statistics have been added. These allow you to easily retrieve statistics for specific seasons, stages, or rounds, instead of having to propagate through includes to retrieve them.
A new include called 'currentPeriod' has been added. It allows for retrieval of the inplay period in a more convenient way compared to using the periods include. Please note the include may return NULL. For example when the match has not yet started, is in half-time, or has ended.
The PlayerStatistic entity now contains a has_values field, indicating whether a Player has any statistics available for the given season.
We have renamed the BEATS type to SUCCESSFUL_DRIBBLES to better reflect the type of statistic.
2023-05-31
Two new endpoints have been added, one for retrieving upcoming Fixtures by tv-station id, and one for retrieving past Fixtures by tv-station id. If you have tv-stations available in your subscription, you automatically have access to these endpoints.
2023-05-30
We have added the currentPeriod include. You can use this as a more convenient way to get the current inplay period for a fixture. Note that the result can be null, for example when the fixture itself is not inplay or the fixture is currently in half-time break.
2023-05-17
The Multiple Fixtures by Id endpoint now allows a maximum of 50 unique id's, this reflects the maximums (per_page) we allow on default paginated endpoints.
2023-04-28
The developer name of Type "Screwsnails Removal" (id: 830) has been renamed to SCREWS_NAILS_REMOVAL for naming convention.
2023-04-18
As per an earlier announcement, we have released some changes to the API on this date.
Removed fields:
State: is_live, is_pending, is_period_end, is_final_state, is_cancelled, is_final_standing_state, is_completed, type_id, is_deleted, is_notstarted, period_length_setting, deactivate_inplay
Period: period_length_internal, final_minute, home_score, away_score
Fixture: last_processed_at
Renamed fields:
Squad: yersey_number was renamed to jersey_number
Added fields:
League: category (basic tier like indicator for the size / popularity of the league. Ranges from 1-4, where 1 are the most 'popular' leagues.
Ordering on endpoints:
Paginated endpoints now support ordering, you can pass a query parameter order with your request to indicate the desired order. Currently order=desc and order=asc are supported. Visit the documentation of the endpoint you are wishing to use ordering on to obtain the field that the ordering applies on.
https://api.sportmonks.com/v3/football/fixtures?api_token=YOUR_TOKEN&page=2&order=descThreshold adjustments:
The threshold of the Latest Updated Fixtures endpoint was lowered from 5 minutes, to 10 seconds. The previous threshold of 5 minutes fetched too much results at times, causing requests to time out.