API-Football offering promises amazing coverage of football (soccer) teams, players, matches, predicted match results and much, much more! In fact, rather than just read a summary of all the possible endpoints, take a look at this nifty high-level diagram they offer as a means of finding your footing, so to speak.
As you can see above, there are two entry points for the logical flow of an average user’s case: Seasons and Countries. The RapidAPI interface provides easy access to this logical starting point via the Countries & Seasons endpoint category.
From there, you will be able to request information that relates directly to a given League.
For example, the following request will return a list of all 129 countries for which API-Football offers coverage.
import requests url = "https://api-football-v1.p.rapidapi.com/v2/countries" headers = { 'x-rapidapi-host': "api-football-v1.p.rapidapi.com", 'x-rapidapi-key': "YOUR RAPID API KEY" } response = requests.request("GET", url, headers=headers) print(response.text)
{1 item "api":{2 items "results":129 "countries":129 items [100 items 0:{3 items "country":"Albania" "code":"AL" "flag":"https://media.api-football.com/flags/al.svg" }...
NOTE: you also get a nifty svg of the various countries’ national flags.
Let’s say that we are interested in Albanian football. To get a list of leagues in Albania, we can turn to the `GET Leagues from Country` endpoint.
import requests url = "https://api-football-v1.p.rapidapi.com/v2/leagues/country/albania" headers = { 'x-rapidapi-host': "api-football-v1.p.rapidapi.com", 'x-rapidapi-key': "YOUR RAPID API KEY" } response = requests.request("GET", url, headers=headers) print(response.text)
The above request will yield the following response:
1 item "api":{2 items "results":2 "leagues":[2 items 0:{13 items "league_id":442 "name":"Superliga" "type":"League" "country":"Albania" "country_code":"AL" "season":2018 "season_start":"2018-08-17" "season_end":"2019-05-30" "logo":"https://media.api-football.com/leagues/442.png" "flag":"https://media.api-football.com/flags/al.svg" "standings":1 "is_current":0 "coverage":{...}6 items } 1:{13 items "league_id":443 "name":"1st Division" "type":"League" "country":"Albania" "country_code":"AL" "season":2018 "season_start":"2018-09-08" "season_end":"2019-05-23" "logo":"https://media.api-football.com/leagues/443.png" "flag":"https://media.api-football.com/flags/al.svg" "standings":1 "is_current":0 "coverage":{...}6 items } ] } }
Next, we can take a look at the teams in Albania’s league, Superlinga. To do so, we just need to use the `GET teams from league id` and pass `442` as our `league_id`, like so:
import requests url = "https://api-football-v1.p.rapidapi.com/v2/teams/league/442" headers = { 'x-rapidapi-host': "api-football-v1.p.rapidapi.com", 'x-rapidapi-key': "YOUR RAPID API KEY" } response = requests.request("GET", url, headers=headers) print(response.text)
The above request will return 10 results, but thankfully our favorite team, Skenderbeu Korce, is first on the list! 😉 As you can see below, we get lots of neat metadata, like the year the team was founded, the venue where they play, and so on. We also got a `team_id` back for each team, which will come in handy for requests about those teams.
{1 item "api":{2 items "results":10 "teams":[10 items 0:{11 items "team_id":605 "name":"Skenderbeu Korce" "code":NULL "logo":"https://media.api-football.com/teams/605.png" "country":"Albania" "founded":1909 "venue_name":"Stadiumi Skënderbeu" "venue_surface":"grass" "venue_address":"Rruga Gjiergi Kastrioti" "venue_city":"Korçë" "venue_capacity":11000
It is certainly worth noting that the above request sequence is not the only way to get here, but it is one route, so to speak, that you might use. At any rate, now that we have a `team_id` we’ll be able to request our first `fixture`, which is an object that represents a game or event.
We will be asking the server for a game record by our newfound `team_id`, but we could also ask for it in innumerable other ways, like `league_id`, time and date constraints and more.
The `fixture` is really pretty neat. It is updated, by and large, every 15 seconds during the course of the game. And, of course, it has some neat data to offer.
To get a sense of what you can access from a `fixture`, let’s ask for one of Skenderbeu Korce’s, shall we? Note that we’re collecting the `team_id` of 605 and passing that in the URI of our request.
import requests url = "https://api-football-v1.p.rapidapi.com/v2/fixtures/team/605" headers = { 'x-rapidapi-host': "api-football-v1.p.rapidapi.com", 'x-rapidapi-key': "YOUR RAPID API KEY" } response = requests.request("GET", url, headers=headers) print(response.text)
And from that, we will get lots and lots of results, but for the sake of time, let’s just take a look at one of them.
{ "fixture_id":134385, "league_id":497, "league":{ "name":"Superliga", "country":"Albania", "logo":"https:\\/\\/media.api-football.com\\/leagues\\/442.png", "flag":"https:\\/\\/media.api-football.com\\/flags\\/al.svg" }, "event_date":"2015-08-29T18:00:00+00:00", "event_timestamp":1440871200, "firstHalfStart":1440871200, "secondHalfStart":1440874800, "round":"Regular Season - 2", "status":"Match Finished", "statusShort":"FT", "elapsed":90, "venue":"Stadiumi Sk\\u00ebnderbeu (Kor\\u00e7\\u00eb)", "referee":null, "homeTeam":{ "team_id":605, "team_name":"Skenderbeu Korce", "logo":"https:\\/\\/media.api-football.com\\/teams\\/605.png" }, "awayTeam":{ "Team_id":577, "team_name":"FK Kukesi", "logo":"https:\\/\\/media.api-football.com\\/teams\\/577.png" }, "goalsHomeTeam":1, "goalsAwayTeam":0, "score":{ "halftime":"0-0", "fulltime":"1-0", "extratime":null, "penalty":null }
Notice that we get information about both teams, start times for both halves, the venue where the game was played, scores and more.
The depth and breadth of the data we have available don’t stop there. We can also access detailed information about players on our beloved team!
To do so, we just need to make use of the Get Players by Team and Season endpoint, like so:
import requests url = "https://api-football-v1.p.rapidapi.com/v2/players/squad/605/2018-2019" headers = { 'x-rapidapi-host': "api-football-v1.p.rapidapi.com", 'x-rapidapi-key': "{Your RapidAPI Key}" } response = requests.request("GET", url, headers=headers) print(response.text)
Which will return the following (limited to the first player on the roster for the sake of space here, but do note that the full roster is returned, like so:
"api":{2 items "results":36 "players":[36 items 0:{13 items "player_id":3591 "player_name":"Dionis Cini" "firstname":"Dionis" "lastname":"Cini" "number":NULL "position":"Defender" "age":19 "birth_date":"23/01/2000" "birth_place":"Korçë" "birth_country":"Albania" "nationality":"Albania" "height":NULL "weight":NULL }
And finally, to get a full accounting of Dionis Cini’s player statistics, we can pull his `player_id` — 3591 — and use that to access his stats, like so:
import requests url = "https://api-football-v1.p.rapidapi.com/v2/players/player/3591" headers = { 'x-rapidapi-host': "api-football-v1.p.rapidapi.com", 'x-rapidapi-key': "37ade4c2c3msha1d663fb3586373p1d8e5ajsnce9df7b9a45e" } response = requests.request("GET", url, headers=headers) print(response.text)
And finally, the above will return a full set of player stats for Dionis Cini, which look like this:
"api":{2 items "results":3 "players":[3 items 0:{31 items "player_id":3591 "player_name":"D. Cini" "firstname":NULL "lastname":NULL "number":NULL "position":"D" "age":19 "birth_date":NULL "birth_place":NULL "birth_country":NULL "nationality":NULL "height":NULL "weight":NULL "injured":"False" "rating":NULL "team_id":605 "team_name":"Skenderbeu Korce" "league":NULL "season":NULL "captain":0 "shots":{...}2 items "goals":{...}3 items "passes":{...}3 items "tackles":{...}3 items "duels":{...}2 items "dribbles":{...}2 items "fouls":{...}2 items "cards":{...}3 items "penalty":{...}5 items "games":{...}3 items "substitutes":{...}3 items }
And that about does it! I hope that you will get lots of great use out of this powerful API, which has been made all that much more accessible by RapidAPI’s careful attention to user experience and success.
Once you’ve got the hang of API-Football, you might also spend some time exploring these related APIs to flesh out your app all that much better.
Leave a Reply