Livescores

In this part we’ll explain what livescores are, how people use them and most importantly, how you can work with them.

What are livescores?

As its name suggests, livescores is the act of displaying real-time sports data to its audience. For example, many livescore websites allow you to see the match’s minute, the people who scored a goal, received a card, etc.

Now, you might wonder how you can get this data yourself. Well, it’s actually quite easy. You can simply use one of our two endpoints!

We have two options:

The first request will give you all the fixtures of the current day. While the second one will provide you with all the fixtures that are currently in-play.

Therefore, the first one would be great if you want to show all the current day’s fixtures in your application. The second one is used for live fixtures.

In the livescores/now endpoint, the fixtures will be available 15 minutes before the match has started and 15 mins after it has ended.

The SportMonks’ livescore endpoints are also highly customizable. Have a look at our API reference guide for all the possible options.

Fixtures of the current day

Now that you know what livescores are let’s put your knowledge to the test.

Let’s look at an example of a possible livescores output. The structure of the API response will be identical to our fixtures endpoint. It’s a basic response, mostly consisting of various ids.

At the section called time, you can see that the fixture will be played today and that it hasn’t started yet, due to the status NS (Not Started).

https://soccer.sportmonks.com/api/v2.0/livescores?api_token={API_TOKEN}

"data": [
        {
            "id": 17162583,
            "league_id": 1779,
            "season_id": 17536,
            "stage_id": 77448678,
            "round_id": 204955,
            "group_id": 244168,
            "aggregate_id": null,
            "venue_id": 3660,
            "referee_id": null,
            "localteam_id": 250106,
            "visitorteam_id": 15541,
            "winner_team_id": null,
            "weather_report": {
                "code": "clouds",
                "type": "overcast clouds",
                "icon": "https://cdn.sportmonks.com/images/weather/04d.png",
                "temperature": {
                    "temp": 81.86,
                    "unit": "fahrenheit"
                },
                "temperature_celcius": {
                    "temp": 27.7,
                    "unit": "celcius"
                },
                "clouds": "90%",
                "humidity": "78%",
                "pressure": 1014,
                "wind": {
                    "speed": "11.41 m/s",
                    "degree": 250
                },
                "coordinates": {
                    "lat": 19.17,
                    "lon": -104
                },
                "updated_at": "2020-10-18T23:45:03.824952Z"
            },
            "commentaries": false,
            "attendance": null,
            "pitch": null,
            "details": null,
            "neutral_venue": false,
            "winning_odds_calculated": false,
            "formations": {
                "localteam_formation": null,
                "visitorteam_formation": null
            },
            "scores": {
                "localteam_score": 0,
                "visitorteam_score": 0,
                "localteam_pen_score": null,
                "visitorteam_pen_score": null,
                "ht_score": null,
                "ft_score": null,
                "et_score": null,
                "ps_score": null
            },
            "time": {
                "status": "NS",
                "starting_at": {
                    "date_time": "2020-10-19 00:00:00",
                    "date": "2020-10-19",
                    "time": "00:00:00",
                    "timestamp": 1603065600,
                    "timezone": "UTC"
                },
                "minute": null,
                "second": null,
                "added_time": null,
                "extra_minute": null,
                "injury_time": null
            },
            "coaches": {
                "localteam_coach_id": null,
                "visitorteam_coach_id": null
            },
            "standings": {
                "localteam_position": 4,
                "visitorteam_position": 1
            },
            "assistants": {
                "first_assistant_id": null,
                "second_assistant_id": null,
                "fourth_official_id": null
            },
            "leg": "1/1",
            "colors": null,
            "deleted": false
        },

You can easily enrich this response with the data you want by using includes. Next, we’re going to include extra information about the local and visitor teams:

https://soccer.sportmonks.com/api/v2.0/livescores?api_token={API_TOKEN}&include=localTeam,visitorTeam

"data": [
        {
            "id": 17162583,
            "league_id": 1779,
            "season_id": 17536,
            "stage_id": 77448678,
            "round_id": 204955,
            "group_id": 244168,
            "aggregate_id": null,
            "venue_id": 3660,
            "referee_id": null,
            "localteam_id": 250106,
            "visitorteam_id": 15541,
            "winner_team_id": null,
            "weather_report": {
                "code": "clouds",
                "type": "overcast clouds",
                "icon": "https://cdn.sportmonks.com/images/weather/04d.png",
                "temperature": {
                    "temp": 81.86,
                    "unit": "fahrenheit"
                },
                "temperature_celcius": {
                    "temp": 27.7,
                    "unit": "celcius"
                },
                "clouds": "90%",
                "humidity": "78%",
                "pressure": 1014,
                "wind": {
                    "speed": "11.41 m/s",
                    "degree": 250
                },
                "coordinates": {
                    "lat": 19.17,
                    "lon": -104
                },
                "updated_at": "2020-10-18T23:45:03.824952Z"
            },
            "commentaries": false,
            "attendance": null,
            "pitch": null,
            "details": null,
            "neutral_venue": false,
            "winning_odds_calculated": false,
            "formations": {
                "localteam_formation": null,
                "visitorteam_formation": null
            },
            "scores": {
                "localteam_score": 0,
                "visitorteam_score": 0,
                "localteam_pen_score": null,
                "visitorteam_pen_score": null,
                "ht_score": null,
                "ft_score": null,
                "et_score": null,
                "ps_score": null
            },
            "time": {
                "status": "NS",
                "starting_at": {
                    "date_time": "2020-10-19 00:00:00",
                    "date": "2020-10-19",
                    "time": "00:00:00",
                    "timestamp": 1603065600,
                    "timezone": "UTC"
                },
                "minute": null,
                "second": null,
                "added_time": null,
                "extra_minute": null,
                "injury_time": null
            },
            "coaches": {
                "localteam_coach_id": null,
                "visitorteam_coach_id": null
            },
            "standings": {
                "localteam_position": 4,
                "visitorteam_position": 1
            },
            "assistants": {
                "first_assistant_id": null,
                "second_assistant_id": null,
                "fourth_official_id": null
            },
            "leg": "1/1",
            "colors": null,
            "deleted": false,
            "localTeam": {
                "data": {
                    "id": 250106,
                    "legacy_id": null,
                    "name": "Colima",
                    "short_code": null,
                    "Twitter": null,
                    "country_id": 458,
                    "national_team": false,
                    "founded": null,
                    "logo_path": "https://cdn.sportmonks.com/images/soccer/team_placeholder.png",
                    "venue_id": null,
                    "current_season_id": 17536
                }
            },
            "visitorTeam": {
                "data": {
                    "id": 15541,
                    "legacy_id": 10081,
                    "name": "Durango",
                    "short_code": null,
                    "Twitter": null,
                    "country_id": 458,
                    "national_team": false,
                    "founded": 1958,
                    "logo_path": "https://cdn.sportmonks.com/images//soccer/teams/21/15541.png",
                    "venue_id": 11287,
                    "current_season_id": 17536
                }
            }

And just like that, we've requested all the fixtures of the day, as well as additional team information.

If this the first time you’ve heard about includes, you might want to check out our includes tutorial.

Visit our statuses and definitions page for information about the fields in the response.

Live fixtures

The only difference between the livescores/now and previous livescores endpoint is that this one will give you all the currently in-play matches. That makes this the go-to endpoint if you want to build a livescore application.

In the example below at the times section again, you can see that the fixture has the “LIVE” status and is currently in the 94th minute.

https://soccer.sportmonks.com/api/v2.0/livescores/now?api_token={API_TOKEN}

{
    "data": [
        {
            "id": 17154603,
            "league_id": 1351,
            "season_id": 17530,
            "stage_id": 77448647,
            "round_id": 204814,
            "group_id": null,
            "aggregate_id": null,
            "venue_id": 733,
            "referee_id": 19361,
            "localteam_id": 132611,
            "visitorteam_id": 132610,
            "winner_team_id": null,
            "weather_report": {
                "code": "clouds",
                "type": "scattered clouds",
                "icon": "https://cdn.sportmonks.com/images/weather/03d.png",
                "temperature": {
                    "temp": 57.43,
                    "unit": "fahrenheit"
                },
                "temperature_celcius": {
                    "temp": 14.1,
                    "unit": "celcius"
                },
                "clouds": "40%",
                "humidity": "54%",
                "pressure": 1011,
                "wind": {
                    "speed": "13.87 m/s",
                    "degree": 160
                },
                "coordinates": {
                    "lat": 51.56,
                    "lon": -1.78
                },
                "updated_at": "2020-10-19T14:45:04.347172Z"
            },
            "commentaries": false,
            "attendance": null,
            "pitch": null,
            "details": null,
            "neutral_venue": false,
            "winning_odds_calculated": false,
            "formations": {
                "localteam_formation": null,
                "visitorteam_formation": null
            },
            "scores": {
                "localteam_score": 0,
                "visitorteam_score": 1,
                "localteam_pen_score": null,
                "visitorteam_pen_score": null,
                "ht_score": "0-0",
                "ft_score": null,
                "et_score": null,
                "ps_score": null
            },
            "time": {
                "status": "LIVE",
                "starting_at": {
                    "date_time": "2020-10-19 13:00:00",
                    "date": "2020-10-19",
                    "time": "13:00:00",
                    "timestamp": 1603112400,
                    "timezone": "UTC"
                },
                "minute": 90,
                "second": "59",
                "added_time": 4,
                "extra_minute": null,
                "injury_time": 1
            },
            "coaches": {
                "localteam_coach_id": null,
                "visitorteam_coach_id": 4598731
            },
            "standings": {
                "localteam_position": 11,
                "visitorteam_position": 13
            },
            "assistants": {
                "first_assistant_id": null,
                "second_assistant_id": null,
                "fourth_official_id": null
            },
            "leg": "1/1",
            "colors": {
                "localteam": {
                    "color": "#881319",
                    "kit_colors": "#79ADE2,#881319,#881319,#79ADE2,#5C8FAE,#FFDF1B,#679FEA"
                },
                "visitorteam": {
                    "color": "#0046A8",
                    "kit_colors": "#C40010,#0046A8,#C40010,#C40010,#999999,#888888,#0046A8"
                }
            },
            "deleted": false
        },

Naturally, this response can also be enriched with includes.

Filtering

Just like with our fixtures endpoint, the livescore endpoint has a lot of filter options. You can filter on the following fields:

Leagues: filter on league ids.
Bookmakers*: filter on bookmaker ids.
Markets*: filter on market ids.
Fixtures: filter on fixture ids.

You can only filter on the bookmakers & markets parameters when you've enriched your response with the odds include.

These filter options allow you to request only the data for certain leagues or fixtures. Filters are beneficial if you want to highlight or exclude certain leagues or fixtures on your application.

For more information about filtering, you can refer to our filtering tutorial again.

Otherwise, if you want to see how livescores can be implemented, please check our how-to build a livescore portal guide.

In our next tutorial, we’re going to discuss the statistics and line-up of a fixture.

PreviousFixtures NextStatistics

Last updated 2 years ago