OpenCricket API documentation

Every ball, one request away.

OpenCricketAPI exposes matches, scorecards, ball-by-ball deliveries, partnerships, phase splits and player matchups through a clean REST interface and an MCP server.

01 · Quickstart

Find a season's matches

cURL · GET /v1/matches
curl "https://opencricketapi.com/v1/matches?competition=comp_indian-premier-league&season=2026" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer oc_live_your_api_key"

Then open one match

200 OK · GET /v1/matches/match_cs_1535465 · abridged
{
  "data": {
    "id": "match_cs_1535465",
    "date": "2026-05-31",
    "end_date": "2026-05-31",
    "season": "2026",
    "competition": {
      "id": "comp_indian-premier-league",
      "name": "Indian Premier League"
    },
    "event_name": "Indian Premier League",
    "stage": "Final",
    "format": "T20",
    "gender": "male",
    "team_type": "club",
    "balls_per_over": 6,
    "overs_limit": 20,
    "venue": {
      "id": "venue_cs_narendra-modi-stadium-ahmedabad",
      "name": "Narendra Modi Stadium",
      "city": "Ahmedabad"
    },
    "teams": [
      {
        "id": "team_cs_gujarat-titans",
        "name": "Gujarat Titans"
      },
      {
        "id": "team_cs_royal-challengers-bengaluru",
        "name": "Royal Challengers Bengaluru"
      }
    ],
    "toss": {
      "team_id": "team_cs_royal-challengers-bengaluru",
      "team": "Royal Challengers Bengaluru",
      "decision": "field"
    },
    "result": "Royal Challengers Bengaluru won by 5 wickets",
    "winner_id": "team_cs_royal-challengers-bengaluru",
    "outcome": {
      "by": {
        "wickets": 5
      },
      "method": null
    },
    "player_of_match": [
      {
        "id": "player_cs_ba607b88",
        "name": "V Kohli"
      }
    ],
    "innings": [
      {
        "number": 1,
        "team_id": "team_cs_gujarat-titans",
        "team": "Gujarat Titans",
        "super_over": false,
        "declared": false,
        "forfeited": false,
        "target": null,
        "total": {
          "runs": 155,
          "wickets": 8,
          "overs": "20",
          "balls": 120
        }
      },
      {
        "number": 2,
        "team_id": "team_cs_royal-challengers-bengaluru",
        "team": "Royal Challengers Bengaluru",
        "super_over": false,
        "declared": false,
        "forfeited": false,
        "target": {
          "overs": 20,
          "runs": 156
        },
        "total": {
          "runs": 161,
          "wickets": 5,
          "overs": "18",
          "balls": 108
        }
      }
    ],
    "source": {
      "name": "Cricsheet",
      "id": "1535465",
      "url": "https://cricsheet.org/matches/1535465",
      "licence": "ODC-By 1.0"
    }
  },
  "meta": {
    "source": "Cricsheet",
    "source_url": "https://cricsheet.org",
    "licence": "ODC-By 1.0",
    "licence_url": "https://opendatacommons.org/licenses/by/1-0/",
    "additional_source": "ESPN, for domestic and youth competitions Cricsheet does not cover"
  }
}
02 · Authentication

Bearer API keys

Every endpoint requires a key. A free Starter key covers matches, scorecards and season tables from the last 12 months, plus competitions, teams, players and search, with 1,000 requests a month and 10 a minute. A Developer key adds the full archive, live scores, fixtures, deliveries, overs, partnerships, phase splits, matchups, fantasy points and venue profiles, with 250,000 requests a month. Raw keys start with oc_live_. OpenCricketAPI stores only a hash.

Authorization: Bearer oc_live_your_api_key
03 · Source and coverage

What is actually available

ARCHIVECricsheet · ODC-By 1.0

Ball-by-ball history

Men's and women's Tests, ODIs, T20Is, ICC events and the major T20 leagues since 2001, refreshed as new matches are published. Some domestic and youth competitions Cricsheet does not cover come from ESPN, and are labelled so.

DERIVEDComputed from deliveries

Overs, partnerships, phases, matchups, fantasy points

Calculated from the delivery and scorecard records. Nothing is estimated, and nothing is added that the records do not contain. Fantasy points return their full rules and every player's event counts.

LIVEESPN · no open licence

Live scores and fixtures

Matches in progress, the live match centre and fixtures for up to 14 days, from ESPN's public scoreboard, refreshed about every 20 seconds and labelled ESPN. Fine for score apps and dashboards, not for in-play betting.

NOT INCLUDEDNo source

Shot direction and pitch maps

Open data does not record where the ball went or pitched, so there are no wagon wheels or beehives.

Every response includes source and licence metadata. See coverage for the full catalog.

04 · API reference

19 endpoints

GET/v1/competitions

Leagues, ICC events and domestic competitions with seasons and match counts.

Starter plan · format, gender, group

GET/v1/competitions/{id}/standings

Points table for a season's league stage: played, won, lost, no result, net run rate and points.

Starter plan · season

GET/v1/competitions/{id}/leaders

Season leaderboards: most runs and wickets, sixes, highest scores, best figures, strike rate and economy.

Starter plan · season, category

GET/v1/matches

Find matches by competition, season, team, venue, format or date range.

Starter plan · competition, season, team, venue, format, gender, from, to, limit, cursor

GET/v1/matches/{id}

Match summary: teams, toss, result, venue, officials and innings totals.

Starter plan

GET/v1/matches/{id}/scorecard

Full batting and bowling scorecard with dismissals and fall of wickets.

Starter plan · innings

GET/v1/matches/{id}/deliveries

Every ball: batter, bowler, runs, extras, wickets and fielders.

Developer plan · innings, over_from, over_to, cursor

GET/v1/matches/{id}/overs

Over-by-over runs and wickets for Manhattan and worm charts.

Developer plan · innings

GET/v1/matches/{id}/partnerships

Partnership runs and balls for every wicket.

Developer plan · innings

GET/v1/matches/{id}/phases

Powerplay, middle and death-over splits for limited-overs innings: the recorded powerplay where the source has it, fixed over ranges otherwise, each labelled.

Developer plan · innings

GET/v1/matches/{id}/fantasy-points

Fantasy points for every player in a match, counted from the scorecard, with the full rules and each player's event counts so you can apply your own scoring.

Developer plan · ruleset

GET/v1/teams/{id}

Team profile with recent matches and competitions.

Starter plan

GET/v1/players/{id}

Player profile with Cricsheet registry ID and career splits by format.

Starter plan

GET/v1/players/{id}/matchups

Batter-versus-bowler history: balls, runs, dismissals, strike rate.

Developer plan · role, opponent, format, limit

GET/v1/venues/{id}

Venue profile: matches hosted, average first-innings score, toss decisions.

Developer plan

GET/v1/live

Matches in progress worldwide with live scores and status, refreshed about every 20 seconds.

Developer plan · state, competition

GET/v1/live/{id}

Live match centre: innings totals, the batters and bowlers in the middle, and the last 18 balls.

Developer plan

GET/v1/fixtures

Upcoming matches for up to 14 days: start time, teams, venue and competition.

Developer plan · from, to, competition

GET/v1/search

Search players, teams, competitions and venues by name.

Starter plan · q, type, limit

05 · Request parameters

Filter matches without learning source IDs

Filters can be combined. Dates are UTC calendar dates. Entity filters use the stable IDs returned by search.

ParameterTypeDescription
competitionstringCompetition ID, e.g. comp_indian-premier-league.
seasonstringSeason label, e.g. 2026 or 2025/26.
teamstringTeam ID, e.g. team_cs_india.
venuestringVenue ID, e.g. venue_cs_eden-gardens-kolkata.
formatenumMatch format. One of: Test, ODI, T20, T10, One-day, Multi-day.
genderenumMen's (male) or women's (female) cricket. One of: male, female.
fromdateMatches on or after this date.
todateMatches on or before this date.
limitintegerMatches per page, newest first. 1-100, default 50.
cursorstringmeta.next_cursor from the previous page.
06 · Integration code

Use the same endpoint from any stack

JavaScript · fetch
const res = await fetch(
  "https://opencricketapi.com/v1/matches/match_cs_1535465/scorecard",
  { headers: { Authorization: `Bearer ${process.env.OPENCRICKET_KEY}` } }
);
if (!res.ok) throw new Error((await res.json()).error.code);
const { data, meta } = await res.json();
console.log(data[1].total, meta.licence);
Python · requests
import os, requests

res = requests.get(
    "https://opencricketapi.com/v1/matches/match_cs_1535465/overs",
    headers={"Authorization": f"Bearer {os.environ['OPENCRICKET_KEY']}"},
    timeout=10,
)
res.raise_for_status()
for over in res.json()["data"][1]["overs"]:
    print(over["over"], over["runs"], over["wickets"])
07 · Response contract

One envelope across every endpoint

Successful requests return data and meta. Failed requests return error and a request ID.

dataThe requested resourceAn object or array with normalized field types.
metaHow the response was producedSource, licence, count and pagination cursor.
errorA stable failure shapeMachine-readable code plus a human-readable message.
200Request completed
400Invalid filters
401Invalid API key
403Plan restriction
404Resource missing
429Quota exhausted
08 · Signature endpoint

Ball-by-ball deliveries

One record per ball, including wides and no-balls. Ball codes are a compact summary. Every delivery also carries the full objects below.

batter / bowlerPlayer IDs and names
runsBatter, extras and total
extrasWides, no-balls, byes, leg byes
wicketsKind, player out and fielders
over / ballPosition in the innings
codeCompact summary: 0, 4, 6, W, 1wd
200 OK · GET /v1/matches/match_cs_1535465/deliveries?innings=2&over_from=18&over_to=18 · abridged
{
  "data": [
    {
      "over": 18,
      "ball": 1,
      "legal_ball": 1,
      "batter_id": "player_cs_800d2d97",
      "bowler_id": "player_cs_12314277",
      "non_striker_id": "player_cs_ba607b88",
      "runs": {
        "batter": 1,
        "extras": 0,
        "total": 1
      },
      "code": "1"
    },
    {
      "over": 18,
      "ball": 2,
      "legal_ball": 2,
      "batter_id": "player_cs_ba607b88",
      "bowler_id": "player_cs_12314277",
      "non_striker_id": "player_cs_800d2d97",
      "runs": {
        "batter": 1,
        "extras": 0,
        "total": 1
      },
      "code": "1"
    }
  ],
  "meta": {
    "source": "Cricsheet",
    "source_url": "https://cricsheet.org",
    "licence": "ODC-By 1.0",
    "licence_url": "https://opendatacommons.org/licenses/by/1-0/",
    "additional_source": "ESPN, for domestic and youth competitions Cricsheet does not cover",
    "match_id": "match_cs_1535465",
    "innings": 2,
    "team_id": "team_cs_royal-challengers-bengaluru",
    "count": 6,
    "total": 6,
    "next_cursor": null
  }
}
09 · Errors

Typed, predictable errors

Errors use stable codes, including invalid_api_key, monthly_quota_exceeded, plan_restriction, match_not_found and feature_not_available. feature_not_available means the source does not publish that data for this match.

{ "error": { "code": "plan_restriction", "message": "Deliveries need a Developer key." } }