Access
Base URL https://api.cricketscore.app/v1. Every request needs the key issued to your site in the X-Api-Key header. Keys are issued per site; ask the CricketScore team for one. Keep it on your server, or ask for your browser origins to be enabled before you call the API from a web page.
The contract is published as OpenAPI 3.1 at /v1/openapi.json. The data is the same data cricketscore.app shows on its pages, refreshed on the same schedule. Missing or delayed feed data stays missing: look at meta.notices and meta.freshness rather than assuming a value.
Resources
/home- The home page: news, featured match with live state, live, up next, upcoming and recent matches, rankings, calendar
/news- Stories with photos. Filters:
category,team,player,updated_since,cursor,limit /news/{id or slug}- One story: our write-up with its full body, or the source page, with sources, entities and related stories.
lang=hifor Hindi /matches- Matches. Filters:
status,date,format,series,team,q /matches/{id}- Summary and live state
/matches/{id}/{section}scorecard,commentary(paged),info,playing-xi,squads,overs,insights,partnerships,man-of-the-match,facts/series,/series/{id},/series/{id}/points-table- Series catalogue, a series' matches and its supplied standings
/teams/{id},/players/{id}- Profiles: form, results, careers, recent performances, related news
/rankingstypeteams, batters, bowlers or allrounders;formattest, odi or t20/calendar,/search?q=- Series and fixtures by date; search across matches, players, teams, series and news
/streams,/streams/{match id}- Which matches stream now. Status is
liveonly while play is on; otherwiseoff-air,endedorupcoming. Link viewers to thewatch_urlon cricketscore.app
Example
curl -H "X-Api-Key: $CRICKETSCORE_KEY" "https://api.cricketscore.app/v1/news?limit=1"
{"data": [{"id": "…", "title": "…", "url": "https://cricketscore.app/news/…", "topic": {"id": "india", "label": "India cricket"},
"photo": {"url": "https://cricketscore.app/media/news/…/w1440.jpg", "width": 1440, "height": 810, "credit": "Photo: …", "credit_required": true, …}}],
"meta": {"freshness": {"news": {"fetched_at": "…", "stale": false}}, "notices": [], "next_cursor": "…"},
"links": {"self": "…", "next": "…"}}
Lists page with cursor: pass meta.next_cursor (or follow links.next) until it is absent.
Photo credits
Every news photo comes with a credit. Show it next to the photo, as cricketscore.app does: “Photo: publisher” for a story's own picture, or the photographer, licence and “via Wikimedia Commons” for freely licensed photos. Use the sizes we serve from cricketscore.app; do not copy photos to other hosts or crop out credits.
Caching and limits
Responses carry an ETag; send it back in If-None-Match and an unchanged resource returns 304 with no body. Cache-Control gives the refresh interval the site itself uses: about 5 seconds for a match in play, 10 seconds for live lists, a minute for news, longer for profiles. Asking more often returns the same data.
Each key has a request rate and a burst. Every response states them in RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and RateLimit-Policy. Over the limit, the API answers 429 with Retry-After. Responses are gzip-compressed when you accept it, and each has an X-Request-ID to quote when you report a problem.
Errors
Errors are application/problem+json with type, title, status, detail and request_id.
- missing-key (401)
- No
X-Api-Keyheader. - invalid-key (401)
- The key is unknown or was revoked.
- origin-not-allowed (403)
- A browser request from an origin that is not enabled for the key.
- rate-limited (429)
- Wait for the seconds in
Retry-After. - bad-request (400)
- A parameter is out of range, or a cursor is no longer in the list.
- not-found (404)
- No such resource or id.
- method-not-allowed (405)
- The API is read-only.
- The score provider did not return this record just now. Retry after the time given.
- api-disabled (503)
- The API is switched off for maintenance.
- internal (500)
- Our fault. Quote the request id.