Guides — Roanuz Cricket API

Source: https://www.cricketapi.com/v5/docs/guides/

Resource Keys

Source: https://www.cricketapi.com/v5/docs/guides/resource-keys

A resource key is an identification string that uniquely identifies a resource within its kind.

Key Types

Type	Format	Example	Description
Country Code	ISO-like	in, au, eng	Country identifier
Association Key	string	icc, bcci, ecb	Cricket board/association
Tournament Key	string	ipl_2026, wc_2026_odi	Specific tournament edition
Match Key	string	ipl_2026_t20_01	Individual match
Team Key	string	csk, mi, ind	Team identifier
Player Key	string	c__player__virat_kohli__abc12	Individual player (long format)

Player Key Formats

Long: c__player__{first}_{last}__{hash} — e.g., c__player__rahul_yadav__fc84b Short: {initial}_{surname} — e.g., p_salt, s_samson

Data Structure

Source: https://www.cricketapi.com/v5/docs/guides/data-structure

Hierarchy

Country
  └── Association (governing body, e.g., ICC, BCCI)
        └── Competition (recurring series, e.g., "ICC Cricket World Cup")
              └── Tournament (specific edition, e.g., "ICC CWC 2019")
                    └── Match (individual game, e.g., "IND vs AUS, Match 14")
                          └── Teams → Players

Key Relationships

• Country → Associations (one country can have multiple: BCCI under ICC)
• Association → Competitions → Tournaments → Matches
• Team → belongs to Association, has squad of Players
• Player → independent resource, accessible without hierarchy traversal
• Match → belongs to Tournament, has Teams, Venue, Score, Innings

Navigation

Forward: Country → Association → Competition → Tournament → Match Backward: Match → Tournament → Competition → Association → Country Cross: Player can be accessed independently of tournament hierarchy

Caching

Source: https://www.cricketapi.com/v5/docs/guides/caching

Recommendations

• Cache fixture/match lists for 5-10 minutes
• Cache live match data for 30-60 seconds
• Cache completed match data for hours/days (it won't change)
• Cache player/team metadata for 24+ hours
• Use ETag/Last-Modified headers when available

Hannibal Implementation

See RoanuzDataAdapter.ts CACHE_TTL constants:

• Fixtures: 300s (5min)
• Match state (live): 60s
• Match state (completed): 3600s (1hr)
• Scorecard (live): 30s
• Scorecard (completed): 3600s (1hr)
• Ball-by-ball: 10s
• Commentary: 30s
• Venue stats: 86400s (24hr)

Error Handling

Source: https://www.cricketapi.com/v5/docs/guides/error-handling

Error Response Format

{
  "status_code": 4xx/5xx,
  "error": {
    "msg": "Human-readable error message",
    "code": "ERROR_CODE"
  }
}

Error Codes

Code	HTTP	Message	Action
A-400-0	400	Invalid input to process	Verify inputs (match keys, etc.)
A-400-2	400	Invalid Project Key provided	Check project key in console
A-400-3	400	Invalid Page Key provided	Use page_key from current response
A-400-4	400	Invalid API Key provided	Check API key in request body
A-401-0	401	Invalid access token to process	Token expired — refresh and retry
A-402-0	402	Project is inactive	Renew Roanuz subscription
A-403-0	403	Access limited to specific user groups	Upgrade plan or check permissions
A-404-0	404	Resource not found	Resource doesn't exist or was deleted
C-400-1	400	Invalid country code provided	Check country code format
P-400-1	400	Subscription not configured	Configure delivery method
P-400-2	400	Invalid push delivery method	Use valid delivery method
P-400-3	400	Delivery method unsupported	Method not available for this resource
P-400-4	400	Resource already subscribed	Already subscribed to this delivery method
P-403-1	403	Subscription disabled on project	Enable push services on account
P-403-2	403	Subscription not authorized	Push unavailable for this resource
UN-500-0	500	Unknown error	Retry after a few seconds

Hannibal Handling

In RoanuzDataAdapter.makeRequest():

if (response.data.error) {
  throw new Error(response.data.error.msg || 'Roanuz API error');
}