Introduction¶

sportmonks is a Python 3.5+ package that implements SportMonks API. While SportMonks (the company) offers data for various sports, this package implements only soccer. There are no plans to implement other sports.

Disclaimer: sportmonks Python package authors are not affiliated with SportMonks the company.

Examples¶

Print today’s games:

>>> from sportmonks.soccer import SoccerApiV2
>>> soccer = SoccerApiV2(api_token='My API token')

>>> fixtures = soccer.fixtures_today(include=('localTeam', 'visitorTeam'))
>>> for f in fixtures:
>>>    print(f['localTeam']['name'], 'plays at home against', f['visitorTeam']['name'])

Randers plays at home against FC Helsingør
Celtic plays at home against Aberdeen
Hibernian plays at home against Rangers
Kilmarnock plays at home against Hearts
Silkeborg plays at home against Lyngby
Hobro plays at home against SønderjyskE
OB plays at home against AGF
AaB plays at home against København

Installation¶

Latest released version can be installed with:

pip install sportmonks

Latest development version can be installed with:

git clone https://www.github.com/Dmitrii-I/sportmonks.git
cd sportmonks
pip install ./

Features¶

sportmonks features focus mainly on convenience:

Methods return only data from the original SportMonks response, with non-data objects dropped. The result is shorter code: [f for f in fixtures_today()] instead of [f for f in fixtures_today()['data']].
Methods return complete data even if the underlying HTTP endpoints are paginated. Fetching all pages is arguably the most common scenario. Not having to write for and while loops to fetch additional pages results in less boilerplate code. The trade-off is that all pages are fetched even when fewer suffice.
Methods with static return values cache the HTTP responses to increase speed and reduce HTTP traffic. A return value is considered static if it is expected to remain fixed in the next hour. The following methods use caching:

sportmonks.soccer reference¶

The soccer module implements the SportMonks soccer HTTP API v2.0.

class sportmonks.soccer.SoccerApiV2(api_token: str)[source]¶

The SoccerApiV2 class provides SportMonks soccer API client.

Parameter api_token is the API token from the SportMonks profile web page.

bookmaker(bookmaker_id: int) → Dict[source]¶: Returns a bookmaker.

bookmakers() → List[Dict][source]¶: Returns all bookmakers.

coach(coach_id: int) → Dict[source]¶: Returns a coach.

commentaries(fixture_id: int) → List[source]¶: Returns commentaries of a fixture. Not all fixtures have commentaries. If a fixture has no commentaries then an empty list is returned.

continent(continent_id: int, includes: tuple = None) → Dict[source]¶

Returns a continent.

Parameter includes specifies objects to include in the response. Maximum level of includes allowed is 10. Valid objects are: countries.

continents(includes: tuple = None) → Dict[source]¶

Returns all continents.

Parameter includes specifies objects to include in the response. Maximum level of includes allowed is 10. Valid objects are: countries.

countries(includes: tuple = None) → List[Dict][source]¶

Returns all countries.

Parameter includes specifies objects to include in the response. Maximum level of includes allowed is 2. Valid objects are: continent, leagues.

country(country_id: int, includes: tuple = None) → Dict[source]¶

Returns a country.

Parameter includes specifies objects to include in the response. Maximum level of includes allowed is 2. Valid objects are: continent, leagues.

fixture(fixture_id: int, includes: tuple = None) → Dict[source]¶

Returns a fixture.

Parameter includes specifies objects to include in the response. Maximum level of includes allowed is 10. Valid objects are: localTeam, visitorTeam, substitutions, goals, cards, other, corners, lineup, bench, sidelined, stats, comments, tvstations, highlights, league, season, round, stage, referee, events, venue, odds, flatOdds, inplay, localCoach, visitorCoach, group, trends.

fixture_tv_stations(fixture_id: int) → List[Dict][source]¶: Returns tv stations broadcasting specified fixture.

fixtures(start_date: datetime.date, end_date: datetime.date, league_ids: List[int] = None, includes: tuple = None) → List[Dict][source]¶

Returns fixtures between start_date and end_date. The dates are inclusive.

Parameter league_ids specifies leagues from which the fixtures will be returned, defaulting to all leagues.

Parameter includes specifies objects to include in the response. Maximum level of includes allowed is 3. Valid objects are: localTeam, visitorTeam, substitutions, goals, cards, other, corners, lineup, bench, sidelined, stats, comments, tvstations, highlights, league, season, round, stage, referee, events, venue, odds, flatOdds, inplay, localCoach, visitorCoach, group, trends.

fixtures_in_play(includes: tuple = None) → List[Dict][source]¶

Returns in-play fixtures. Note that in-play is defined by SportMonks as fixtures currently played, plus fixtures that will begin within 45 minutes, and fixtures that ended less than 30 minutes ago.

Parameter includes specifies objects to include in the response. Maximum level of includes allowed is 10. Valid objects are: localTeam, visitorTeam, substitutions, goals, cards, other, corners, lineup, bench, sidelined, stats, comments, tvstations, highlights, league, season, round, stage, referee, events, venue, odds, flatOdds, inplay, localCoach, visitorCoach, group, trends.

fixtures_today(league_ids: List[int] = None, includes: tuple = None) → List[Dict][source]¶

Returns today’s fixtures, played and to be played.

Parameter league_ids specifies leagues from which the fixtures will be returned, defaulting to all leagues.

Parameter includes specifies objects to include in the response. Maximum level of includes allowed is 10. Valid objects are: localTeam, visitorTeam, substitutions, goals, cards, other, corners, lineup, bench, sidelined, stats, comments, tvstations, highlights, league, season, round, stage, referee, events, venue, odds, flatOdds, inplay, localCoach, visitorCoach, group, trends.

head_to_head_fixtures(team_ids: set, includes: tuple = None) → List[Dict][source]¶

Returns all head-to-head fixtures of two teams specified by team_ids.

Parameter includes specifies objects to include in the response. Maximum level of includes allowed is 2. Valid objects are: localTeam, visitorTeam, substitutions, goals, cards, other, lineup, bench, stats, comments, tvstations, highlights, league, season, round, stage, referee, events, venue, trends.

in_play_odds(fixture_id: int) → List[Dict][source]¶: Returns in-play odds of a fixture.

league(league_id: int, includes: tuple = None) → Dict[source]¶

Returns a league.

Parameter includes specifies objects to include in the response. Maximum level of includes allowed is 2. Valid objects are: country, season, seasons. The season include returns current season of the league. The seasons include returns all seasons of the league, including the current season.

leagues(includes: tuple = None) → List[Dict][source]¶

Returns all leagues.

Parameter includes specifies objects to include in the response. Maximum level of includes allowed is 2. Valid objects are: country, season, seasons. The season include returns current season of the league. The seasons include returns all seasons of the league, including the current season.

market(market_id: int) → Dict[source]¶: Returns a market.

markets() → List[Dict][source]¶: Returns all betting markets, e.g. ‘3Way Result’, ‘Home/Away’.

meta()[source]¶: Returns meta data that includes your SportMonks plan, subscription, and available sports.

player(player_id: int) → Dict[source]¶: Returns a player.

pre_match_odds(fixture_id: int) → List[Dict][source]¶: Returns pre-match odds of a fixture.

round(round_id: int, includes: tuple = None) → Dict[source]¶

Returns a round.

Parameter includes specifies objects to include in the response. Maximum level of includes allowed is 2. Valid objects are: fixtures, results, season, league.

rounds(season_id: int, includes: tuple = None) → List[Dict][source]¶

Returns rounds of a season.

Parameter includes specifies objects to include in the response. Maximum level of includes allowed is 2. Valid objects are: fixtures, results, season, league.

season(season_id: int, includes: tuple = None) → Dict[source]¶

Returns a season.

Parameter includes specifies objects to include in the response. Maximum level of includes allowed is 10. Valid objects are: league, stages, rounds, fixtures, upcoming, results, groups.

season_results(season_id: int, includes: tuple = None) → List[Dict][source]¶

Returns completed fixtures of a season.

Parameter includes specifies objects to include in the response. Maximum level of includes allowed is 1. Valid objects are: localTeam, visitorTeam, substitutions, goals, cards, other, corners, lineup, bench, sidelined, stats, comments, tvstations, highlights, league, season, round, stage, referee, events, venue, odds, flatOdds, inplay, localCoach, visitorCoach, group, trends.

season_stages(season_id: int, includes: tuple = None) → List[Dict][source]¶

Returns stages of a season.

Parameter includes specifies objects to include in the response. Maximum level of includes allowed is 2. Valid objects are: fixtures, results, season, league.

season_venues(season_id: int) → List[Dict][source]¶: Returns venues of specified season.

seasons(includes: tuple = None) → List[Dict][source]¶

Returns all seasons.

Parameter includes specifies objects to include in the response. Maximum level of includes allowed is 2. Valid objects are: league, stages, rounds, fixtures, upcoming, results, groups.

squad(season_id: int, team_id: int, includes: tuple = None) → List[Dict][source]¶

Returns a squad. A squad is a set of players that played for a team during a season.

Parameter includes specifies objects to include in the response. Maximum level of includes allowed is 3. Valid objects are: player, position.

stage(stage_id: int, includes: tuple = None) → Dict[source]¶

Returns a stage.

Parameter includes specifies objects to include in the response. Maximum level of includes allowed is 2. Valid objects are: fixtures, results, season, league.

standings(season_id: int, live: bool = False, group_id: int = None, includes: tuple = None) → List[Dict][source]¶

Returns standings of a season.

Parameter live specifies whether standings should also take into account in-play fixtures.

Parameter group_id specifies for which group to return the standings. Groups are found in tournaments like the FIFA World Cup (e.g. Group A has group ID 185).

Parameter includes specifies objects to include in the response. Maximum level of includes allowed is 2. Valid objects are: team, league, season, round, stage.

team(team_id: int, includes: tuple = None) → Dict[source]¶

Returns a team.

Parameter includes specifies objects to include in the response. Maximum level of includes allowed is 3. Valid objects are: country, squad, coach, transfers, sidelined, stats, venue, fifaranking, uefaranking, visitorFixtures, localFixtures, visitorResults, localResults, latest, upcoming.

team_fixtures(start_date: datetime.date, end_date: datetime.date, team_id: int, includes: tuple = None) → List[Dict][source]¶

Returns fixtures between start_date and end_date for a team specified by team_id.

Parameter includes specifies objects to include in the response. Maximum level of includes allowed is 3. Valid objects are: localTeam, visitorTeam, substitutions, goals, cards, other, corners, lineup, bench, sidelined, stats, comments, tvstations, highlights, league, season, round, stage, referee, events, venue, odds, flatOdds, inplay, localCoach, visitorCoach, group, trends.

team_stats(team_id: int) → Dict[source]¶: Returns stats of a team.

teams(season_id: int, includes: tuple = None) → List[Dict][source]¶

Returns all teams that played during a season.

Parameter includes specifies objects to include in the response. Maximum level of includes allowed is 3. Valid objects are: country, squad, coach, transfers, sidelined, stats, venue, fifaranking, uefaranking, visitorFixtures, localFixtures, visitorResults, localResults, latest, upcoming.

top_scorers(season_id: int, includes: tuple = None) → Dict[source]¶

Returns top scorers of a season. Three types of top scorers are returned: most goals, most assists, and most cards.

Parameter includes specifies objects to include in the response. Maximum level of includes allowed is 3. Valid objects are: goalscorers.player, goalscorers.team cardscorers.player, cardscorers.team, assistscorers.player, assistscorers.team.

venue(venue_id: int) → Dict[source]¶: Returns a venue.

video_highlights(fixture_id: int = None, includes: tuple = None) → List[Dict][source]¶

Returns links to video highlights of all fixtures or of a fixture specified by fixture_id.

Parameter includes specifies objects to include in the response. Maximum level of includes allowed is 2. Valid objects are: fixture.