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.

PreviewThis contract is published ahead of launch. API keys open to the waitlist first. The example responses on this page are real data, built from the Indian Premier League final on 2026-05-31.

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

{
  "data": {
    "id": "match_cs_1535465",
    "competition": {
      "id": "comp_indian-premier-league",
      "name": "Indian Premier League"
    },
    "season": "2026",
    "stage": "Final",
    "format": "T20",
    "date": "2026-05-31",
    "venue": "Narendra Modi Stadium, Ahmedabad",
    "teams": [
      {
        "id": "team_cs_gujarat-titans",
        "name": "Gujarat Titans",
        "short": "GT"
      },
      {
        "id": "team_cs_royal-challengers-bengaluru",
        "name": "Royal Challengers Bengaluru",
        "short": "RCB"
      }
    ],
    "toss": {
      "decision": "field",
      "winner": "Royal Challengers Bengaluru"
    },
    "innings": [
      {
        "number": 1,
        "team": "Gujarat Titans",
        "runs": 155,
        "wickets": 8,
        "overs": "20"
      },
      {
        "number": 2,
        "team": "Royal Challengers Bengaluru",
        "runs": 161,
        "wickets": 5,
        "overs": "18"
      }
    ],
    "result": "Royal Challengers Bengaluru won by 5 wickets",
    "player_of_match": [
      "V Kohli"
    ]
  },
  "meta": {
    "source": "Cricsheet",
    "licence": "ODC-By 1.0",
    "source_url": "https://cricsheet.org/matches/1535465"
  }
}

02 · Authentication

Bearer API keys

Every endpoint requires a key. A free Starter key covers matches, scorecards, competitions, teams, players and search with 5,000 requests a month. A Developer key adds deliveries, overs, partnerships, phase splits, matchups 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.

DERIVEDComputed from deliveries

Overs, partnerships, phases, matchups

Calculated from the delivery records. Nothing is estimated, and nothing is added that the deliveries do not contain.

NOT YETPlanned

Live scoring

The archive is not a live feed. Live ball-by-ball data is planned and will be labelled clearly when it arrives.

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

13 endpoints

GET/v1/competitions

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

Starter plan · format, gender, group

GET/v1/matches

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

Starter plan · competition, season, team, format, gender, from, to, 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

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

GET/v1/matches/{id}/partnerships

Partnership runs and balls for every wicket.

Developer plan

GET/v1/matches/{id}/phases

Powerplay, middle and death-over splits for limited-overs innings.

Developer plan

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 · opponent, format

GET/v1/venues/{id}

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

Developer plan

GET/v1/search

Search players, teams, competitions and venues by name.

Starter plan · q, type

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.

Parameter	Type	Description
`competition`	string	Stable competition ID, for example comp_indian-premier-league.
`season`	string	Season label as published: 2026, or 2025/26 for seasons that span two years.
`team`	string	Stable team ID, for example team_cs_india.
`format`	enum	Test, ODI, T20, One-day or Multi-day.
`gender`	enum	male or female.
`from / to`	date	Match start date range in YYYY-MM-DD.
`cursor`	string	Opaque cursor from meta.next_cursor for the next 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 · abridged

{
  "data": [
    {
      "innings": 2,
      "over": 18,
      "ball": 1,
      "code": "1"
    },
    {
      "innings": 2,
      "over": 18,
      "ball": 2,
      "code": "1"
    }
  ],
  "meta": {
    "innings": 2,
    "count": 6,
    "cursor": null,
    "source": "Cricsheet"
  }
}

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." } }