States

Using the include

The state include allows you to retrieve additional information about the current state of a fixture. Including the state in your API request ensures that the response includes details about the current state of the fixture, such as whether the match is ongoing, has ended, is postponed, or is in any other specific state.

You can use the state include in your API request by adding the &include= parameter and setting it to state to ensure that the response includes information about the current state of the fixture. For a GET All Fixtures request, that would look like this:

https://api.sportmonks.com/v3/football/fixtures&include=state

Filtering

If you want to filter fixtures based on specific states, you can use the &filter= parameter in your API request. Then you can filter like this: &filter=fixtureStates:StateIDs. This is optional and depends on your use case. So, if, for example, you want to manage fixtures that are delayed or interrupted, use the state information to filter and handle such scenarios like this:

https://api.sportmonks.com/v3/football/fixtures&include=state&filters=fixtureStates:16;18

You can find all the different Fixture State IDs on this page:

pageFixture States

State interactions

Understanding how the different fixture states interact and transition between each other is crucial for effectively managing football data. Below is an in-depth explanation of how the various fixture states in our API can interact and interchange with one another:

State	Transitions to	Why?
NS (Not Started)	SUSPENDED	Game has been suspended and will continue at a later time or day
NS	CANCELLED	Game has been cancelled
NS	WALKOVER	Win has been awarded to a participant because there are no other contestants
NS	ABANDONED	Game has been abandoned and will continue at a later time or day
NS	DELAYED	Game is delayed, so it will start later
NS	AWARDED	The winner is being decided externally
NS	POSTPONED	The game is postponed
NS	INPLAY_1ST_HALF	The game starts
INPLAY_1ST_HALF	HT	When the game reaches half-time
HT	INPLAY_2ND_HALF	When half-time has been concluded
INPLAY_2ND_HALF	FT	When the 2nd half has concluded
FT	BREAK	When no winner has been decided (usually in knock-out fixtures)
BREAK	INPLAY_ET	When Extra Time starts
INPLAY_ET	ETB	When the 1st half of extra time ends
ETB	INPLAY_ET	When the short break between extra time ends
INPLAY_ET	AET	When extra time ends
AET	PEN_BREAK	When no winner was decided and the match goes to penalties
PENB	INPLAY_PENALTIES	When the penalty shoot-out starts.
INPLAY_PENALTIES	FT_PEN	When the penalty shoot-out has concluded

Other states

Awarded (AWAR): Winner is being decided externally.

No further transitions. The game remains in the Awarded state.

Interrupted (INT): The game has been interrupted, possibly due to bad weather.

Transitions to various states based on the reason for interruption.

Awaiting Updates (AU): Can occur when there is a connectivity issue or something.

No immediate transition. The game remains in the Awaiting Updates state until further updates.

Deleted (DEL): Game is not available anymore via normal API calls because it has been replaced.

Can be retrieved by adding &filters=deleted to a request to the Fixtures endpoint.

Pending (PEN): The fixture is awaiting an update.

No immediate transition. The game remains in the Pending state until further updates.