How to use the API-Football API with Python

API-Football provides amazing coverage of football (soccer) teams, players, matches, predicted match results and more! You can see a complete list of all the possible endpoints in this 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.

Connect to the API-Football API

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 and, as you can see below, we get a lot of 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.

Connect to the API-Football APITo 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 a lot 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 Sku00ebnderbeu (Koru00e7u00eb)",
   "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 selected 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)

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! There are a ton of different ways to use this API, let us know what you come up with!

Connect to the API-Football APIOnce 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.

1. Football Prediction
2. The Rundown
3. Football Science