Welcome to soccer-api-wrapper’s documentation!

As writing GET and POST requests multiple times to get data can be frustrating, the library will streamline the process of retrieving information about soccer by making the API calls under the hood as an API Wrapper. So if anyone wants to create an app or a bot on apps like Telegram, they will be able to make use of this library to easily create their apps or bots for anything related to soccer without having to make api calls every single time.

Getting Started

To get started using this library follow the instructions below.

Installing

If you run into an issue please check the closed issues on the github, although feel free to re-open a new issue if you find an issue that’s been closed for a few months. The codebase can and does run into similar issues as it has before, because the api this library is based on changes things up.

pip install soccer_api_wrapper

Quick Start Guide

In order to use this library, you will need to first get an API token from https://www.football-data.org/ as this library is completely based on that API and you will need to provide that token every time you use the functions listed below

In the first verion of this library, only the premier league is supported. Other league functionalities will be added in future versions.

from soccer_api_wrapper import soccerapi
# To check the current standings in the premier league
teams = soccerapi.get_epl_team_standings("YourAPIToken")
for team in teams:
    # prints information about the team strating from club at position 1
    print(team)

Similarly, there are other functions you can call on soccerapi after importing it:

soccerapi.get_competitions_for_team(api_token, team_id)

Function that returns the competitions a particular team is in

Parameters
Returns

list of competitions

soccerapi.get_epl_matchday(api_token, matchday)

Function that returns matches happening on a particular matchday in the premier league

Parameters
Returns

dict

soccerapi.get_epl_team_standings(api_token)

Function that returns the standings of the premier league

Parameters

api_token (str) – api token user gets after registering at https://www.football-data.org/

Returns

dict

Raises

KeyError – If the maximum threshold of api calls is reached

soccerapi.get_epl_teams(api_token)

Function that returns the premier league teams in the current campaign

Parameters

api_token (str) – api token user gets after registering at https://www.football-data.org/

Returns

dict

soccerapi.get_epl_top_scorers(api_token)

Function that returns the top scorers in the premier league

Parameters

api_token (str) – api token user gets after registering at https://www.football-data.org/

Returns

dict

Raises

KeyError – If the maximum threshold of api calls is reached

soccerapi.get_head_to_head_matches(api_token, home_team_id, away_team_id)

Function that returns head to head matches between two given teams

Parameters

  • api_token (str) – api token user gets after registering at https://www.football-data.org/

  • home_team_id (int) – id of the home team

  • away_team_id (int) – id of the away team

Returns

dict

soccerapi.get_head_to_head_stats(api_token, home_team_id, away_team_id)

Function that returns head to head stats between two given teams including amount of wins/losses/goals

Parameters

  • api_token (str) – api token user gets after registering at https://www.football-data.org/

  • home_team_id (int) – id of the home team

  • away_team_id (int) – id of the away team

Returns

dict

soccerapi.get_matches(api_token, competition_name)

Function that returns matches happening in the competition requested

Parameters

  • api_token (str) – api token user gets after registering at https://www.football-data.org/

  • competition_name (str) – Name of competition for which matches are requested

Returns

dict

soccerapi.get_player_by_position(api_token, team_id, position)

Function that returns the players in a team at play at the position specified

Parameters

  • api_token (str) – api token user gets after registering at https://www.football-data.org/

  • team_id (int) – id of the team

  • position (str) – position of players requested

Returns

list of players

soccerapi.get_player_info(api_token, player_id)

Function that returns information about a player

Parameters
Returns

dict

soccerapi.get_players_of_team(api_token, team_id)

Function that returns the players in a team

Parameters
Returns

list of players

soccerapi.get_recent_matches(api_token)

Function that returns recent matches that happened/will happen

Parameters

api_token (str) – api token user gets after registering at https://www.football-data.org/

Returns

dict

soccerapi.get_team_info(api_token, team_id)

Function that returns information about a particular premier league team

Parameters
Returns

dict

soccerapi.get_team_matches(api_token, team)

Function that returns matches for a particular team

Parameters

  • api_token (str) – api token user gets after registering at https://www.football-data.org/

  • team (str) – name of the football in the format laid out in the doc

Returns

dict

soccerapi.get_ucl_matches(api_token)

Function that returns matches happening in the champions league

Parameters

api_token (str) – api token user gets after registering at https://www.football-data.org/

Returns

dict

Examples Of Library Usage