# 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: 1. [**Livescores**](https://football-postman.sportmonks.com/#462efa38-0bb4-40b4-8f28-1bffe9228400) 2. [**Livescores/now**](https://football-postman.sportmonks.com/#fb0b146e-2ab6-4c36-9abc-cc50c84d0bc5) 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. {% hint style="info" %} In the [**livescores/now endpoint,**](https://football-postman.sportmonks.com/#fb0b146e-2ab6-4c36-9abc-cc50c84d0bc5) the fixtures will be available 15 minutes before the match has started and 15 mins after it has ended. {% endhint %} The SportMonks’ livescore endpoints are also highly customizable. Have a look at our [**API reference guide**](https://football-postman.sportmonks.com/) 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[ ](https://documenter.getpostman.com/view/11949411/T1LPD6nj?version=latest#b7f79045-eac3-40c5-b114-24c5b438f62c)[**fixtures endpoint.**](https://football-postman.sportmonks.com/#b7f79045-eac3-40c5-b114-24c5b438f62c) 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). {% tabs %} {% tab title="Request" %} ```javascript https://soccer.sportmonks.com/api/v2.0/livescores?api_token={API_TOKEN} ``` {% endtab %} {% tab title="Response" %} ```javascript "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 }, ``` {% endtab %} {% endtabs %} 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: {% tabs %} {% tab title="Request" %} ```javascript https://soccer.sportmonks.com/api/v2.0/livescores?api_token={API_TOKEN}&include=localTeam,visitorTeam ``` {% endtab %} {% tab title="Response" %} ```javascript "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 } } ``` {% endtab %} {% endtabs %} 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 [i**ncludes tutorial.**](/v2/tutorials/enriching-your-response/includes.md) {% hint style="info" %} Visit our [**statuses and definitions**](/v2/api-references/statussus-and-definitions.md) page for information about the fields in the response. {% endhint %} ### **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. {% tabs %} {% tab title="Request" %} ```javascript https://soccer.sportmonks.com/api/v2.0/livescores/now?api_token={API_TOKEN} ``` {% endtab %} {% tab title="Response" %} ```javascript { "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 }, ``` {% endtab %} {% endtabs %} Naturally, this response can also be enriched with includes. ### **Filtering** Just like with our fixtures endpoint, the [**livescore endpoint** ](https://football-postman.sportmonks.com/#b850a1c2-9775-4828-8cce-3799532e06aa)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. {% hint style="info" %} You can only filter on the bookmakers & markets parameters when you've enriched your response with the [**odds include**](/v2/tutorials/odds-and-predictions/extra-odds.md)**.** {% endhint %} 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**](/v2/tutorials/filtering-limiting-and-sorting/filtering.md) again. Otherwise, if you want to see how livescores can be implemented, please check our [**how-to build a livescore portal guide.**](/v2/how-to-guides/livescores-and-fixtures/how-to-build-a-livescore-website.md) In our next tutorial, we’re going to discuss the statistics and line-up of a fixture. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.sportmonks.com/v2/tutorials/schedule-fixtures-and-livescores/livescores.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.