Imagine you’re at a party. Your friends are talking about the World Cup Final that’s about to take place: The Netherlands will play against Spain. You’re having a big discussion about which team deserves to lift the trophy. Everyone has their own opinion which leads to a never-ending discussion.
All of a sudden your best friend takes his phone out of his pocket. He begins to tell about the statistics of both teams of the tournament so far. Everyone stops talking and starts to listen carefully to him. He brings out some good points like match statistics, individual player statistics, and predictions.
Thanks to his input you all agree that based on the statistics, The Netherlands deserve to lift the trophy. You want to know where he gets this information from, so you ask. Your friend tells about this football application that he’s been making HIMSELF. You’re very excited: “If he can do it, so can I!”.
You start by browsing the internet for a good football data provider. You finally find one, but what are the beginner steps to start your implementation? How does it work and what are some useful tricks?
SportMonks Football Pro API
One of the most important parts of making a high-quality football website is to have the correct data.
Maybe you think you’ve found the perfect provider for your football application. However, the price of the product starts rising fast when you start making requests. It seems like the provider charges you rapidly for extra requests!
With the SportMonks Football API calls packages, you will have enough calls to build a professional Football Application and update your Livescores every second.
One of the main benefits of the SportMonks Football API is the well-structured JSON responses. Thanks to this, the data is very easy to read and implement in your own football application. In addition, the rest-full API makes it easy to use in other programming languages as well: Phyton, PHP, Ruby, Java, etc.: it’s all possible!
Now, let’s dive into how the SportMonks Football API is structured.
SportMonks Football API Structure
You will need to understand the API’s structure before you can start making API requests. Your implementation will run more smoothly once you have a basic understanding of the structure, and it is fairly easy to understand. Please note there is also a search API where you can find the ID’s of a team, player, or league based on your search criteria.
Continents
Let’s start at the top of the API Structure. You can use the continents endpoint if you want to see all the continents available in your package. Each continent will have its own unique ID. This makes it easy to recognize a specific continent and you can use the ID in other endpoints as well. The Continents endpoint might be a useful endpoint for you if you want to show Football Leagues ordered by continent on your Football application.
An example request could be:
var req = unirest("GET", "https://football-pro.p.rapidapi.com/api/v2.0/continents");
req.query({
"tz": "Europe%2FAmsterdam",
});
{
"data": [
{
"id": 1,
"name": "Europe"
},
{
"id": 2,
"name": "Asia"
},
{
"id": 3,
"name": "Africa"
},
{
"id": 4,
"name": "Oceania"
},
{
"id": 5,
"name": "Antarctica"
},
{
"id": 6,
"name": "North America"
},
{
"id": 7,
"name": "South America"
}
]
Countries
Of course, each continent contains countries. Based on the previous response, you can request the countries per continent.
Let’s say you want all the countries in your plan from Europe. As you can see, the unique ID per continent is very helpful. *
var req = unirest("GET", "https://football-pro.p.rapidapi.com/api/v2.0/continents/1");
req.query({
"tz": "Europe%2FAmsterdam",
"include": "countries"
});
You will get all the countries in Europe with their basic information. Just like each continent has its unique ID, the countries have this as well. Maybe you’re interested in Spain:
"data": [
"id": 32,
"name": "Spain",
"image_path": "https://cdn.sportmonks.com/images/countries/png/short/es.png",
"extra": {
"continent": "Europe",
"sub_region": "Southern Europe",
"world_region": "EMEA",
"fifa": "ESP",
"iso": "ESP",
"iso2": "ES",
"longitude": "-3.550692558288574",
"latitude": "40.396026611328125",
"flag": "<svg xmlns="http://www.w3.org/2000/svg" height="500" width="750">……….
*Please note every player, fixture, country, continent, etc. had its own unique ID.
Leagues
Let’s move on with the previous examples. You’re interested in Spain and want to have all the leagues in your plan from this country. You can easily use the country ID of Spain to request this:
var req = unirest("GET", "https://football-pro.p.rapidapi.com/api/v2.0/countries/32");
req.query({
"tz": "Europe%2FAmsterdam",
"include": "leagues"
});
Now you will get all the existing football leagues in your plan from Spain, including La Liga.
{
"id": 564,
"active": true,
"type": "domestic",
"legacy_id": 19,
"country_id": 32,
"logo_path": "https://cdn.sportmonks.com/images/soccer/leagues/564.png",
"name": "La Liga",
"is_cup": false,
"current_season_id": 16326,
"current_round_id": 175900,
"current_stage_id": 77444988,
"live_standings": true,
"coverage": {
"predictions": true,
"topscorer_goals": true,
"topscorer_assists": true,
"topscorer_cards": true
}
},
Seasons
Each league has their season(s). You can retrieve historical seasons or only the current one. The difference between this is described in the documentation pages.
Let’s say you only want the active football season:
var req = unirest("GET", "https://football-pro.p.rapidapi.com/api/v2.0/leagues/564");
req.query({
"tz": "Europe%2FAmsterdam",
"include": "season"
});
{
"data": {
"id": 564,
"active": true,
"type": "domestic",
"legacy_id": 19,
"country_id": 32,
"logo_path": "https://cdn.sportmonks.com/images/soccer/leagues/564.png",
"name": "La Liga",
"is_cup": false,
"current_season_id": 16326,
"current_round_id": 175900,
"current_stage_id": 77444988,
"live_standings": true,
"coverage": {
"predictions": true,
"topscorer_goals": true,
"topscorer_assists": true,
"topscorer_cards": true
},
"season": {
"data": {
"id": 16326,
"name": "2019/2020",
"league_id": 564,
"is_current_season": true,
"current_round_id": 175900,
"current_stage_id": 77444988
}
}
You can use the Seasons Endpoint now you have the active season ID. On this endpoint, you can request a lot of information like the season results, schedule, topscorers and many more. Please check the API Reference Guide for more information.
You probably want information about a specific football match? Let’s see how you can access this.
Fixtures
El Classico: Real Madrid – FC Barcelona is one of the biggest matches of the year. How can you access this fixture via the SportMonks Football API?
You already know how to retrieve a particular season of the La Liga. Let’s take the current one: Season ID: 16326.
One of the options is to use the season endpoint to request for example the fixtures per season. Your request will look like this:
var req = unirest("GET", "https://football-pro.p.rapidapi.com/api/v2.0/seasons/16326");
req.query({
"tz": "Europe%2FAmsterdam",
"include": "fixtures"
});
{
"id": 11896061,
"league_id": 564,
"season_id": 16326,
"stage_id": 77444988,
"round_id": 175894,
"group_id": null,
"aggregate_id": null,
"venue_id": 2020,
"referee_id": 11710,
"localteam_id": 3468,
"visitorteam_id": 83,
"winner_team_id": 3468,
"weather_report": {
"code": "clouds",
"type": "broken clouds",
"icon": "https://cdn.sportmonks.com/images/weather/04n.png",
"temperature": {
"temp": 52.52,
"unit": "fahrenheit"
},
"temperature_celcius": {
"temp": 11.4,
"unit": "celcius"
},
"clouds": "75%",
"humidity": "87%",
"pressure": 1009,
"wind": {
"speed": "14.99 m/s",
"degree": 190
},
"coordinates": {
"lat": 40.42,
"lon": -3.7
},
"updated_at": "2020-03-01T21:45:03.979962Z"
},
"commentaries": true,
"attendance": 78357,
"pitch": null,
"details": null,
"neutral_venue": false,
"winning_odds_calculated": true,
"formations": {
"localteam_formation": "4-1-4-1",
"visitorteam_formation": "4-4-2"
},
"scores": {
"localteam_score": 2,
"visitorteam_score": 0,
"localteam_pen_score": null,
"visitorteam_pen_score": null,
"ht_score": "0-0",
"ft_score": "2-0",
"et_score": null,
"ps_score": null
},
"time": {
"status": "FT",
"starting_at": {
"date_time": "2020-03-01 20:00:00",
"date": "2020-03-01",
"time": "20:00:00",
"timestamp": 1583092800,
"timezone": "UTC"
},
"minute": 93,
"second": null,
"added_time": null,
"extra_minute": null,
"injury_time": null
},
"coaches": {
"localteam_coach_id": 407775,
"visitorteam_coach_id": 459056
},
"standings": {
"localteam_position": 2,
"visitorteam_position": 1
},
"assistants": {
"first_assistant_id": 11711,
"second_assistant_id": 12024,
"fourth_official_id": 21455
},
"leg": "1/1",
"colors": {
"localteam": {
"color": "#F0F0F0",
"kit_colors": "#F0F0F0,#F0F0F0,#F0F0F0,#F0F0F0,#EEEEEE,#EEEEEE,#F0F0F0"
},
"visitorteam": {
"color": "#002B87",
"kit_colors": "#002B87,#940014,#002B87,#002B87,#5C8FAE,#FFDF1B,#022857"
}
},
With this request, you will get all the fixtures of the season. You can enrich this response by adding nested include. For example extra information about the local and visitor team:
var req = unirest("GET", "https://football-pro.p.rapidapi.com/api/v2.0/seasons/16326");
req.query({
"tz": "Europe%2FAmsterdam",
"include": "fixtures.localTeam,fixtures.visitorTeam"
});
"localTeam": {
"data": {
"id": 3468,
"legacy_id": 117,
"name": "Real Madrid",
"short_code": "RMA",
"twitter": "@realmadrid",
"country_id": 32,
"national_team": false,
"founded": 1902,
"logo_path": "https://cdn.sportmonks.com/images//soccer/teams/12/3468.png",
"venue_id": 2020,
"current_season_id": 16326
}
},
"visitorTeam": {
"data": {
"id": 83,
"legacy_id": 130,
"name": "Barcelona",
"short_code": "FCB",
"twitter": "@FCBarcelona",
"country_id": 32,
"national_team": false,
"founded": 1899,
"logo_path": "https://cdn.sportmonks.com/images//soccer/teams/19/83.png",
"venue_id": 9236,
"current_season_id": 16326
}
}
},
The fixture endpoint is subdivided over 5 categories where you can request the endpoint. We’re going to discuss a few of them.
- Fixtures by ID
- Fixtures by Date
- Fixtures by Date Range
- Fixtures by Date Range for a Team
- Multiple Fixtures by ID
- Get Last Updated
Fixtures by Date Range for a Team
Another way to find the El Classico match is to request all the fixtures of a certain team by date range. This will make it a lot easier if you know that Real Madrid – FC Barcelona is played on the first of March.
var req = unirest("GET", "https://football-pro.p.rapidapi.com/api/v2.0/fixtures/between/2020-03-01/2020-03-01/3468");
req.query({
"tz": "Europe%2FAmsterdam",
"include": "fixtures.localTeam,fixtures.visitorTeam"
});
*3468 is the Team ID of Real Madrid. You can best retrieve this via the Search API.
Fixtures by ID
The Fixture endpoint provides information about Games in particular Leagues. There are always 2 teams involved in a Fixture. For many developers, Fixtures is the main endpoint for their app/website. Be aware your access is limited to Fixtures of Leagues, available in the Plan you are subscribed to.
Responses of the Fixture endpoint are highly customizable because there are many Includes available to extend the response. Requests often start with the Includes localTeam and VisitorTeam. Events, Stats, Lineups, Comment, Trends, etc. are often added as well. Please visit the Documentation Pages for more information.
An example request could be:
var req = unirest("GET", "https://football-pro.p.rapidapi.com/api/v2.0/fixtures/11896061");
req.query({
"tz": "Europe%2FAmsterdam",
"include": "visitorTeam,localTeam,events,lineup,stats"
});
LiveScores
You can obtain live data of Games of the current day and live data for In Play Games via the Livescore endpoint. The Livescore endpoint is almost identical to our fixtures endpoint. It provides real-time data about Game information and Events like Goals, Cards, Substitutions, Line-ups, In Play Stats etc. Just like the fixtures endpoint, these responses are highly customizable.
var req = unirest("GET", "https://football-pro.p.rapidapi.com/api/v2.0/livescores/now");
req.query({
"tz": "Europe%2FAmsterdam",
"include": "visitorTeam,localTeam,events,lineup,stats"
});
Please visit the Documentation Pages for more information.
Search API
As mentioned, SportMonks also has a search API. With this endpoint, it’s very easy to search for the ID of a team, league or player. Nevertheless, we wanted to show you how the API is structured and how relationships work.
Hopefully, this was just the basic information you needed to start your own amazing football application. Maybe you will be the person who can show your own awesome football app on the next party! Please don’t be afraid to contact SportMonks with any questions or concerns, they’re always happy to help!
Leave a Reply