Usage

Recent matches

Summary().matches lists the matches on ESPNcricinfo’s results page. Pass a date to look back; ESPN returns about two weeks of matches ending on that day.

>>> from espncricinfo.match import Match
>>> refs = Match.get_recent_matches(date="2026-02-28")
>>> len(refs)
195
>>> refs[0]
MatchRef(series_id=1523975, match_id=1523981)
>>> series_id, match_id = refs[0]  # MatchRefs unpack like tuples

For one day only, Match.get_matches_on("2026-10-20") keeps the matches played that day, multi-day matches included on each of their days. Summary(date=...) wraps the same call; its result is in .matches.

A single match

A match needs only its match ID, the number in a match page URL. Passing the series ID too (Match(1478914, 1478874), or MatchRef.to_match()) skips a redirect. Loading a match starts a headless WebKit browser.

>>> m = Match(1478914)
>>> m.description
'IND Women v AUS Women'
>>> m.match_class
'WT20I'
>>> m.result
'IND Women won by 17 runs'
>>> m.batting_scorecard[0][0]["name"], m.batting_scorecard[0][0]["runs"]
('S Mandhana', 82)
>>> m.bowling_scorecard[0][0]["name"], m.bowling_scorecard[0][0]["wickets"]
('D Brown', 0)

To work through every match of a format, list a year’s match IDs from Statsguru (1 Test, 2 ODI, 3 T20I, 8/9/10 the women’s formats) and load each one. Each load starts a browser, so a year of Tests takes a minute or two:

>>> ids = Match.get_match_ids(2023, 1)
>>> len(ids)
34
>>> Match(ids[0]).description
'New Zealand v Pakistan'

batting_scorecard and bowling_scorecard hold one list per innings and one dict per player. over_by_over gives runs and wickets for every over, and each m.innings entry has fours and sixes.

m.ground loads the ground record (Ground in espncricinfo.grounds): name, city, country, capacity.

Players

The player ID is the number at the end of a player’s profile URL.

>>> from espncricinfo.player import Player
>>> p = Player(277916)
>>> p.full_name
'Ajinkya Madhukar Rahane'
>>> p.get_data(file_name="rahane_tests.csv", match_format=1, data_type="batting")

get_data writes one row per match (85 Tests for Rahane); get_career_summary and get_career_averages write the summary tables from the same Statsguru page.

Series, seasons and teams

>>> from espncricinfo.series import Series
>>> ipl = Series(1449924)
>>> ipl.name
'Indian Premier League'
>>> season = ipl.current_season
>>> season.year, len(season.teams)
(2025, 10)
>>> season.teams[0].name
'Chennai Super Kings'

Seasons that cross New Year, like the Big Bash League’s, each have their own series ID. Look one up by the label ESPNcricinfo shows:

>>> bbl = Series(8044)
>>> season = bbl.season("2024/25")  # also 2024, "2024-25" or "2024/2025"
>>> season.label, season.series_id
('2024/25', 1443056)

series.season_objects lists every season and season.match_refs that season’s matches. series.matches collects MatchRefs across all seasons (1,254 for the IPL), and series.current_matches keeps those in progress. team.players loads the squad on demand. ESPN’s records for some bilateral tours are incomplete, for example listing one team for a two-team series.