Matches

class Match(match_id, series_id=None)

One match, loaded from its ESPNcricinfo full-scorecard page.

Loading starts a headless WebKit browser, because the site’s CDN refuses plain HTTP clients. Example values below are for Match(1478914, 1478874).

Parameters:

• match_id (int)

• series_id (int)

match_id: int

ESPNcricinfo match id.

json: dict[str, Any]

The parsed page, reshaped by _normalize. Prefer the attributes.

series_id: int

ESPNcricinfo series id, as ESPN reports it for this match.

description: str

'IND Women v AUS Women'.

match_title: str

Match title within the series, e.g. '3rd T20I'.

match_class: str

Format, e.g. 'WT20I', 'T20', 'Test'.

status: str

ESPN status, e.g. 'result'; 'dormant' for unplayed matches.

result: str

Result line, e.g. 'IND Women won by 17 runs'.

season: str

Season label, e.g. '2025/26'.

series_name: str | None

'India Women in Australia'.

date: str

Start date, 'YYYY-MM-DD'.

start_datetime: str

Start time in UTC, ISO 8601.

canceled: bool

True if ESPN marks the match as canceled.

ground_id: str

ESPN ground id.

ground_name: str

'Adelaide Oval'.

town_name: str | None

Town or city of the ground.

lighting: str

Floodlight setting, e.g. 'night'.

scheduled_overs: int | None

Scheduled overs per side; None for Tests.

innings_list: list[str]

Innings numbers as strings, ['1', '2'].

innings: list[dict[str, Any]]

team id, runs, wickets, overs, fours, sixes (None where ESPN has no figures) and ESPN’s raw lists.

Type:

One dict per innings

all_innings: list[dict[str, Any]]

ESPN’s raw innings records, including partnerships and commentary.

rosters: dict[str, Any] | None

ESPN’s raw squads (teamPlayers), or None.

team_1: MatchTeam

First-listed side.

team_2: MatchTeam

Second-listed side.

team_1_id: str

team_1['team_id'].

team_2_id: str

team_2['team_id'].

team_1_abbreviation: str

team_1['team_abbreviation'], e.g. 'IND-W'.

team_2_abbreviation: str

team_2['team_abbreviation'].

team_1_players: list[dict[str, Any]]

ESPN’s raw player records for team 1.

team_2_players: list[dict[str, Any]]

ESPN’s raw player records for team 2.

team_1_innings: dict[str, Any] | None

Team 1’s first innings record, or None if it has not batted.

team_2_innings: dict[str, Any] | None

Team 2’s first innings record, or None if it has not batted.

team_1_run_rate: float | None

Team 1’s runs per over, or None.

team_2_run_rate: float | None

Team 2’s runs per over, or None.

team_1_overs_batted: float | None

Overs team 1 batted, or None.

team_2_overs_batted: float | None

Overs team 2 batted, or None.

home_team: str | None

Abbreviation of the home side, or None.

batting_first: str | None

Abbreviation of the side that batted first, or None.

match_winner: str | None

Abbreviation of the winner; None for no result, a tie or an unplayed match.

toss_winner: str | None

Team id of the toss winner, or None.

toss_decision_name: str | None

'bat' or 'bowl', or None before the toss.

event_url: str

Core API event URL.

details_url: str

Core API URL for the ball-by-ball details.

espn_api_url: str

ESPN site API summary URL.

batsmen(innings)

ESPN’s raw batting records for a 1-based innings, or None.

Parameters:

innings (int)

Return type:

list[dict[str, Any]] | None

bowlers(innings)

ESPN’s raw bowling records for a 1-based innings, or None.

Parameters:

innings (int)

Return type:

list[dict[str, Any]] | None

fows(innings)

ESPN’s raw fall-of-wicket records for a 1-based innings, or None.

Parameters:

innings (int)

Return type:

list[dict[str, Any]] | None

extras(innings)

Extras for a 1-based innings: total, byes, leg byes, wides, no balls.

Parameters:

innings (int)

Return type:

dict[str, int | None] | None

property batting_scorecard: list[list[BattingEntry]]

one list per innings, one row per batter.

Outer list is indexed by innings order; inner list has one entry per batsman. Players who did not bat have batted=False and numeric fields as None.

Example:

for i, innings in enumerate(m.batting_scorecard, 1):
    print(f"Innings {i}:")
    for b in innings:
        print(b["name"], b["runs"], b["balls"], b["dismissal"])

Type:

Batting scorecard

property bowling_scorecard: list[list[BowlingEntry]]

one list per innings, one row per bowler.

Outer list is indexed by innings order; inner list has one entry per bowler.

Example:

for i, innings in enumerate(m.bowling_scorecard, 1):
    print(f"Innings {i}:")
    for b in innings:
        print(b["name"], b["wickets"], b["runs"], b["overs"])

Type:

Bowling scorecard

property ground: Ground

The match’s ground, loaded on first access (one request).

property over_by_over: list[list[OverEntry]]

one list per innings, one row per over.

Empty for an innings ESPN has no over data for, as with early Tests.

Example:

for over in m.over_by_over[0]:
    print(over["over"], over["runs"], over["total_runs"])

Type:

Runs and wickets per over

static get_recent_matches(date=None)

Return MatchRefs for the matches on ESPNcricinfo’s results page.

ESPN returns roughly the two weeks of matches ending on date. Use get_matches_on() for the matches played on one day.

Parameters:

date (date | str | None) – A datetime.date or a string in YYYY-MM-DD or DD-MM-YYYY form; defaults to today.

Returns:

The listed matches, most recent first.

Return type:

list[MatchRef]

static get_matches_on(date=None)

Return MatchRefs for the matches being played on one day.

A match counts if the day falls between its start and end dates, so a Test appears on each of its days.

Parameters:

date (date | str | None) – A datetime.date or a string in YYYY-MM-DD or DD-MM-YYYY form; defaults to today.

Returns:

The matches on that day.

Return type:

list[MatchRef]

static get_match_ids(year, match_format=1)

Return the ids of every international match of one format in a year.

Reads Statsguru’s results table, so it covers matches back to 1877. Pass each id to Match to load it; each load starts a browser.

Parameters:

• year (int) – Calendar year, e.g. 2023.

• match_format (int) – Statsguru class: 1 Test, 2 ODI, 3 T20I, 8 women’s Test, 9 women’s ODI, 10 women’s T20I.

Returns:

Match ids in the order Statsguru lists them (by date).

Return type:

list[int]

class MatchRef(series_id, match_id)

A lightweight reference to an ESPN Cricinfo match.

Stores the series_id and match_id needed to construct a Match. Supports dict and CSV serialization and tuple unpacking for backward compatibility.

Example:

from espncricinfo.match_ref import MatchRef

ref = MatchRef(series_id=1478874, match_id=1478914)
series_id, match_id = ref          # tuple unpacking still works
m = ref.to_match()                 # hydrate a full Match object
d = ref.to_dict()                  # {"series_id": 1478874, "match_id": 1478914}
row = ref.to_csv_row()             # ["1478874", "1478914"]

Parameters:

• series_id (int)

• match_id (int)

to_dict()

Return {"series_id": int, "match_id": int}.

Return type:

dict[str, int]

classmethod from_dict(d)

Construct from a mapping with series_id and match_id keys.

Parameters:

d (Mapping[str, Any])

Return type:

MatchRef

classmethod from_core_event_url(url)

Construct from a core ESPN event reference.

Parameters:

url (str)

Return type:

MatchRef

to_csv_row()

Return [str(series_id), str(match_id)] for use with csv.writer.

Return type:

list[str]

classmethod from_csv_row(row)

Construct from a 2-element sequence [series_id, match_id].

Parameters:

row (Sequence[str | int])

Return type:

MatchRef

to_match()

Hydrate a full Match object.

Triggers a Playwright fetch — use only when you need full match data.

Return type:

Match

class Summary(date=None)

Recent matches as MatchRef objects.

Uses Match.get_recent_matches() which scrapes the ESPN Cricinfo results page via Playwright. Pass an optional date string (YYYY-MM-DD or DD-MM-YYYY) to get matches for a specific day; defaults to today.

Example:

from espncricinfo.summary import Summary

for ref in Summary().matches:
    m = ref.to_match()
    print(m.description)

# Tuple unpacking also works:
for series_id, match_id in Summary().matches:
    print(series_id, match_id)

Parameters:

date (date | str | None)

matches: list[MatchRef]

The listed matches.

Row types

Scorecard rows and teams are plain dicts at runtime; these TypedDicts give their keys and value types.

class BattingEntry

One row of Match.batting_scorecard.

Numeric fields are None for players who did not bat.

name: str | None

full_name: str | None

player_id: int | None

runs: int | None

balls: int | None

minutes: int | None

fours: int | None

sixes: int | None

strike_rate: float | None

is_out: bool

dismissal: str

batted: bool

class OverEntry

One over of Match.over_by_over.

over: int

runs: int

wickets: int

total_runs: int

total_wickets: int

class BowlingEntry

One row of Match.bowling_scorecard.

name: str | None

full_name: str | None

player_id: int | None

overs: float | None

maidens: int | None

runs: int | None

wickets: int | None

economy: float | None

wides: int | None

no_balls: int | None

dots: int | None

class MatchTeam

One side of a match, as held in Match.team_1 and team_2.

team_id: str

team_abbreviation: str

team_name: str

team_long_name: str

player: list[dict[str, Any]]