Match Details API ★ USED

Source: https://www.cricketapi.com/v5/docs/match-rest-api Refresh: Multiple intervals — varies by match time Delivery: HTTP REST, WebHook, WebSocket, Firebase

Overview

Get real-time scorecard, match status, team lineups, player of the match, team scores, individual player scores, and other comprehensive match information. Updates delivered faster than every other data provider in the industry.

Endpoint

GET /v5/cricket/{project_key}/match/{match_key}/

Headers

rs-token: <access_token>

Sample Request (Node.js)

const response = await axios.get(
  `https://api.sports.roanuz.com/v5/cricket/${projectKey}/match/${matchKey}/`,
  { headers: { 'rs-token': token } }
);

Response Structure

The match endpoint returns comprehensive match data including:

{
  "status_code": 200,
  "data": {
    "key": "ipl_2026_t20_01",
    "name": "CSK vs MI, 1st Match",
    "status": "started",
    "format": "t20i",
    "start_at": 1711234567,
    "teams": {
      "a": {
        "key": "csk",
        "name": "Chennai Super Kings",
        "short_name": "CSK",
        "players": { ... }
      },
      "b": { ... }
    },
    "tournament": { "key": "ipl_2026", "name": "IPL 2026" },
    "venue": { "key": "chepauk", "name": "MA Chidambaram Stadium" },
    "toss": {
      "winner": { "key": "csk", "name": "Chennai Super Kings" },
      "decision": "bat"
    },
    "play": {
      "live": {
        "runs": 156,
        "wickets": 3,
        "overs": [14, 6],
        "target": null,
        "batting_team": "a"
      },
      "related_balls": {
        "529536": { ... },
        "529792": { ... }
      },
      "first_batting": "a",
      "target": { "runs": 186 }
    },
    "innings": {
      "a_1": {
        "runs": 185,
        "wickets": 4,
        "overs": 20,
        "batting": [ ... ],
        "bowling": [ ... ]
      },
      "b_1": { ... }
    },
    "score": {
      "a": { "runs": 185, "wickets": 4, "overs": 20 },
      "b": { "runs": 120, "wickets": 3, "overs": 15.2 }
    },
    "result": "CSK won by 65 runs",
    "winner": { "key": "csk", "name": "Chennai Super Kings" }
  }
}

Key Fields

Field	Type	Description
key	string	Match identifier
status	string	not_started, started, completed, cancelled
teams.a / teams.b	Object	Team data with players
toss	Object	Toss winner and decision (bat/bowl)
play.live	Object	Current live score state
play.related_balls	Object	Recent ball events (numeric keys → ball objects)
play.first_batting	string	"a" or "b" — which team batted first
play.target	Object	{ runs: number } — target score if chasing
innings	Object	Innings data keyed as a_1, b_1, a_2, b_2
score.a / score.b	Object	Team scores (runs, wickets, overs)
winner	Object	Winning team (key, name)

Toss Data Formats

The toss.winner field can come in multiple formats:

1. Object: { key: 'csk', name: 'Chennai Super Kings' }
2. String reference: 'a' or 'b' (referring to teams.a or teams.b)
3. Team key: 'csk', 'mi', etc.

Hannibal's adapter handles all three formats.

Related Balls Format

See 05-ball-by-ball.md for the ball object structure. In the match endpoint, related balls are returned as an object with numeric keys (ball IDs) mapping to ball objects.

Hannibal Usage

File: RoanuzDataAdapter.ts

Used in multiple methods:

• getMatchState(matchId) → full match state normalization
• getRelatedBalls(matchId) → extract play.related_balls for live ball events
• getVenueStatistics(venueName) → fetch match details for statistics calculation

const data = await this.makeRequest(`/match/${matchId}/`);
const state = this.normalizeMatchState(matchId, data);

Normalization

The adapter normalizes Roanuz match data to canonical CricketMatchState:

• Maps status string to canonical CricketMatchStatus
• Parses innings data into Innings[]
• Extracts toss info handling all winner formats
• Parses play.live for current match state
• Extracts play.related_balls for recent ball events