Football API 3.0
Odds Core
Football API
API 2 (Deprecated) Widgets Contact

Livescores

Display all livescores of your favourite leagues and teams. The livescore endpoints allow you to retrieve up-to-date livescores that interest you quickly.

You can choose a variety of endpoints to retrieve the livescores of that particular moment.

This section will briefly discuss all the options available to request livescores.

An overview of all available options:

  • GET All Inplay Livescores: returns all the inplay fixtures.

  • GET All Livescores: Returns the fixtures 15 minutes before the game starts. It will also disappear 15 minutes after the game is finished.

  • GET Latest Updated Livescores: returns all livescores that have received updates within 10 seconds.

For the Livescore endpoints this is the base URL:

https://api.sportmonks.com/v3/football/livescores/

Per endpoint the rest of the URL requires additional information. We will explain this per endpoint.

Requesting livescores

GET All Inplay Livescores

Returns all the live fixtures. For example, if you want all leagues' matches within your subscription that will start within 15 minutes or are already live or have finished in the past 15 minutes. This comes in handy when you want all the actual games that are inplay or will be soon. Also, the matches that just ended

https://api.sportmonks.com/v3/football/livescores/inplay

This response is different for any plan. If you are subscribed to the free plan, you will receive matches of the Danish Superliga and the Scottish Premiership. 

https://api.sportmonks.com/v3/football/livescores/inplay?api_token=YOUR_TOKEN
Response
{
  "data": {
    "id": 18535517,
    "sport_id": 1,
    "league_id": 501,
    "season_id": 19735,
    "stage_id": 77457866,
    "group_id": null,
    "aggregate_id": null,
    "round_id": 274719,
    "state_id": 5,
    "venue_id": 8909,
    "name": "Celtic vs Rangers",
    "starting_at": "2022-09-03 11:30:00",
    "result_info": "Celtic won after full-time.",
    "leg": "1/1",
    "details": null,
    "length": 90,
    "placeholder": false,
    "last_processed_at": "2023-03-02 17:47:38",
    "has_odds": true,
    "starting_at_timestamp": 1662204600
  },
//And more!

Let’s evaluate the response:

  • id: the unique fixture id

  • sport_id: the sport related to the fixture

  • league_id: the league the fixture belongs to

  • season_id: refers to the season the fixture belongs to

  • stage_id: refers to the stage the fixture is played in

  • group_id: refers to the group the fixture is played in

  • aggregate_id: refers to the aggregate the fixture is played at

  • round_id: refers to the round the fixture is played at

  • state_id: refers to the state the fixture is played at

  • venue_id: refers to the venue the fixture is played at

  • name: represents the name of the fixture

  • starting_at: datetime object representing the start time

  • result_info: textual representation of the final result info

  • leg: represents the leg of the fixture

  • details: represents details about the fixture

  • length: length of the fixture (minutes)

  • placeholder: indicates if the fixture is a placeholder

  • last_processed_at: the date and time the fixture was last processed

  • has_odds: indicates if the fixture has odds available

  • starting_at_timestamp: the starting timestamp

Please be aware that in the livescores endpoint, the fixtures will be available 15 minutes before the match has started and 15 mins after it has ended.

GET All Livescores

Returns all the fixtures of the current day. This will give an overview of all the matches that will be played on the current day. The number of matches will be higher than the previous endpoint which only gives live matches and matches that will start in 15 minutes or have ended in the past 15 minutes. Therefore, this is the best endpoint to use if you want to show all matches that will happen today.

The URL to request all the fixtures of the current day is the same as the base URL All you have to do is authorize the request with your API token. Check our authentication section for more info.

https://api.sportmonks.com/v3/football/livescores?api_token=YOUR_TOKEN
Response
{
  "data": {
    "id": 18535517,
    "sport_id": 1,
    "league_id": 501,
    "season_id": 19735,
    "stage_id": 77457866,
    "group_id": null,
    "aggregate_id": null,
    "round_id": 274719,
    "state_id": 5,
    "venue_id": 8909,
    "name": "Celtic vs Rangers",
    "starting_at": "2022-09-03 11:30:00",
    "result_info": "Celtic won after full-time.",
    "leg": "1/1",
    "details": null,
    "length": 90,
    "placeholder": false,
    "last_processed_at": "2023-03-02 17:47:38",
    "has_odds": true,
    "starting_at_timestamp": 1662204600
  },
//And more!

Please note that the response is based on the leagues in your plan. Therefore, if you’re missing a specific one, it’s possible that you don’t have access to it. Check our league tutorial for more info.

GET Last Updated Livescores

Your response will be smaller than the “all livescores” response and only returns you all livescores that have received updates within 10 seconds. This way, you will see the most important changes very quickly.

All you have to do is add the latest characteristic to the base URL:

https://api.sportmonks.com/v3/football/livescores/latest

https://api.sportmonks.com/v3/football/livescores/latest?api_token=YOUR_TOKEN
Response
{
  "data": {
    "id": 18535517,
    "sport_id": 1,
    "league_id": 501,
    "season_id": 19735,
    "stage_id": 77457866,
    "group_id": null,
    "aggregate_id": null,
    "round_id": 274719,
    "state_id": 5,
    "venue_id": 8909,
    "name": "Celtic vs Rangers",
    "starting_at": "2022-09-03 11:30:00",
    "result_info": "Celtic won after full-time.",
    "leg": "1/1",
    "details": null,
    "length": 90,
    "placeholder": false,
    "last_processed_at": "2023-03-02 17:47:38",
    "has_odds": true,
    "starting_at_timestamp": 1662204600
  },
//And more!

Adding useful information

As you’ve learnt in the includes tutorial, you can enrich your request with includes. This section will discuss some of the most common requests used on the livescores endpoints.

First of all, you can find a list of all available includes on the endpoint pages. The most common includes are:

  • scores

  • participants

  • statistics.type

  • events

  • lineups

This results in the below request:

https://api.sportmonks.com/v3/football/livescores/inplay?api_token=YOUR_TOKEN&include=scores;participants;statistics.type;events;lineups

Selecting and filtering

In our filtering tutorial you’ve learnt how to select specific fields or filter only on the data you’re interested in. Our API returns a set of data related to the fixtures by default. We can imagine you’re not interested in all the data the API returns.

Let’s say you’re only interested in the fixtures of the Danish Superliga (league id: 172).

https://api.sportmonks.com/v3/football/livescores/inplay?api_token=YOUR_TOKEN&filters=fixtureLeagues:172&include=league

Check our filtering tutorial for more tips and tricks.

PreviousLivescores and fixturesNextFixtures

Last updated