# YorkerAPI

> The cricket data API. 18 cricket data tools for AI agents. REST API + MCP server.

Full reference with response shapes: https://yorkerapi.com/llms-full.txt
MCP server setup: https://yorkerapi.com/llms-install.md
MCP server for AI agents (clients, prompts, every tool): https://yorkerapi.com/mcp
Datasets with live coverage by season: https://yorkerapi.com/docs/atlas
Tool catalogue with JSON Schema: https://mcp.yorkerapi.com/v1/tools
OpenAPI 3.1 spec: https://mcp.yorkerapi.com/openapi.json

## Quick Start

- API base URL: https://mcp.yorkerapi.com
- Auth: `Authorization: Bearer YOUR_API_KEY` or `x-api-key: YOUR_API_KEY`
- MCP server: `https://mcp.yorkerapi.com/mcp?key=YOUR_API_KEY`
- 500 free credits every month, no credit card required
- REST API responses include `X-Credits-Used` and `X-Credits-Remaining` headers
- Seasons: the season string a competition uses: a year (2025) or the two-year span of a winter series (2024/25). Team codes like team ids are slugs of the side's name, e.g. india, india-women, mumbai-indians. Match ids like 1422119 (a match id; list matches to find one).

## Data timing and rights

- Odds and props are pre-game only. captured_at is when a line was captured (the page says exactly what it means for each kind of row); where props are held, rows also carry scheduled_start and minutes_before_scheduled_start (negative when captured after the scheduled start).
- Records are overwritten when sources correct them; no revision history is kept.
- You may store the data, train models, backtest, and build commercial products that show your users what you derive. You may not redistribute the data, or odds as a raw feed, as a dataset or API of its own. After an account closes, stored data is for internal use only.
- YorkerAPI is independent, not an official league partner, and grants no league rights.
- Full answers: https://yorkerapi.com/docs/timing-and-rights

## Which Tool Should I Use?

### Basic lookup
- Upcoming and live matches in every competition, with both sides' ratings -> get_schedule (2 cr)
- Results by competition, season, team, venue or date, with scores and margins -> get_matches (2 cr)
- Our Elo ratings by format, best first -> get_ratings (2 cr)

### Static reference
- Every competition we hold with its key, format, match count and seasons -> list_competitions (1 cr)
- Team ids for international sides and franchises, men's and women's -> list_teams (1 cr)
- Find a player's id by name, or list a team's players -> search_players (1 cr)

### Multi-table
- One match in full: batting and bowling cards, ratings and every book's opening and closing price -> get_match (5 cr)
- Match-winner prices by sportsbook, opening and closing, from mid-2020 -> get_odds (5 cr)

### Time-series
- Ball-by-ball rows for a match, a batter or a bowler, with our win probability -> get_deliveries (10 cr)
- A match's win-probability worm over by over, and the balls that swung it -> get_win_probability (10 cr)
- In-play prices beside our win probability, lined up to the exact ball -> get_market_vs_model (10 cr)
- Every pregame snapshot by book, the market line over time, and in-play prices -> get_line_movement (10 cr)

### Stats + aggregation
- A career by format: runs, average, strike rate, wickets, economy, hundreds, best figures -> get_player (5 cr)
- A player split by season, competition, phase (powerplay, middle, death) or format -> get_player_stats (5 cr)
- A player's matches with batting and bowling in each innings -> get_player_matches (5 cr)
- A batter against a bowler: balls, runs, strike rate, dots and every dismissal -> get_matchup (5 cr)
- Leaders in runs, average, strike rate, sixes, wickets, economy -> get_leaders (5 cr)
- How a ground plays: par totals, batting first against chasing, toss effect -> get_venue (5 cr)

## Intents

- "Which competitions do you have, and since when?" -> list_competitions
- "What are the IPL 2025 team ids?" -> list_teams
- "What is Virat Kohli's player id?" -> search_players
- "Who plays in the next three days?" -> get_schedule
- "Every IPL 2025 result" -> get_matches
- "Show me the IPL 2025 final scorecard" -> get_match
- "Every ball of the last two overs of the IPL final" -> get_deliveries
- "Jasprit Bumrah's career by format" -> get_player
- "How does Kohli bat in the powerplay compared with the death overs?" -> get_player_stats
- "Joe Root's last three Tests" -> get_player_matches
- "Steve Smith against Bumrah" -> get_matchup
- "Who took the most wickets in IPL 2025?" -> get_leaders
- "Does the side batting first win at the Wankhede?" -> get_venue
- "Who is the best Test side right now?" -> get_ratings
- "When did the IPL final swing?" -> get_win_probability
- "What were the closing odds for the IPL final?" -> get_odds
- "How did the price move before and during the IPL final?" -> get_line_movement
- "Where did the market and the model disagree during the IPL final?" -> get_market_vs_model

## Pages

- [Docs](https://yorkerapi.com/docs): every endpoint, with parameters and a live example response.
- [Data changelog](https://yorkerapi.com/changelog): when each dataset was last refreshed and what it runs through, read from the database.
- [Status](https://yorkerapi.com/status): measured uptime for the website and MCP server over 24 hours, 7 days and 90 days, probed every five minutes from outside our own infrastructure, with incidents and data freshness.
- [Data atlas](https://yorkerapi.com/docs/atlas): what exists, which endpoints expose it, and where coverage is partial.
- [Teams](https://yorkerapi.com/teams): a page per club with its record, season figures and recent games.
- [Players](https://yorkerapi.com/players): a page per cricketer with 50 or more matches: batting and bowling by format (runs, average, strike rate, wickets, economy) and recent matches.
- [Data timing and rights](https://yorkerapi.com/docs/timing-and-rights): what timestamps mean, when each dataset updates, whether lines are pre-game, and what the terms allow.
- [Pricing](https://yorkerapi.com/pricing): credits per call and what a plan includes.
- [Sign up](https://yorkerapi.com/signup): 500 free credits every month, no card.

### Live odds

- [Upcoming cricket odds](https://yorkerapi.com/odds): Match-winner prices for upcoming cricket matches by sportsbook, with the draw in Tests. Stored snapshots taken before the first ball.

### Other leagues

- [The Tests data API](https://yorkerapi.com/test): Tests ball by ball since 2001: Test matches, men's and women's, with sportsbook prices from July 2020. REST and MCP. MCP: https://mcp.yorkerapi.com/mcp/test
- [The ODIs data API](https://yorkerapi.com/odi): ODIs ball by ball since 2002: One Day Internationals, men's and women's, with sportsbook prices from July 2020. REST and MCP. MCP: https://mcp.yorkerapi.com/mcp/odi
- [The T20Is data API](https://yorkerapi.com/t20i): T20Is ball by ball since 2005: Twenty20 Internationals, men's and women's, with sportsbook prices from August 2022. REST and MCP. MCP: https://mcp.yorkerapi.com/mcp/t20i
- [The IPL data API](https://yorkerapi.com/ipl): IPL ball by ball since 2008: every Indian Premier League season, with sportsbook prices from September 2020. REST and MCP. MCP: https://mcp.yorkerapi.com/mcp/ipl
- [The BBL data API](https://yorkerapi.com/bbl): BBL ball by ball since 2011: every Big Bash League season, with sportsbook prices from December 2020. REST and MCP. MCP: https://mcp.yorkerapi.com/mcp/bbl
- [The PSL data API](https://yorkerapi.com/psl): PSL ball by ball since 2016: every Pakistan Super League season, with sportsbook prices from February 2023. REST and MCP. MCP: https://mcp.yorkerapi.com/mcp/psl
- [The CPL data API](https://yorkerapi.com/cpl): CPL ball by ball since 2013: every Caribbean Premier League season, with sportsbook prices from September 2022. REST and MCP. MCP: https://mcp.yorkerapi.com/mcp/cpl
- [The T20 Blast data API](https://yorkerapi.com/blast): T20 Blast ball by ball since 2014: the T20 Blast, English county Twenty20, with sportsbook prices from June 2023. REST and MCP. MCP: https://mcp.yorkerapi.com/mcp/blast
- [The Hundred data API](https://yorkerapi.com/hundred): The Hundred ball by ball since 2021: every men's season of The Hundred, with sportsbook prices from August 2022. REST and MCP. MCP: https://mcp.yorkerapi.com/mcp/hundred
- [The SA20 data API](https://yorkerapi.com/sa20): SA20 ball by ball since 2023: every SA20 season. REST and MCP. MCP: https://mcp.yorkerapi.com/mcp/sa20
- [The ILT20 data API](https://yorkerapi.com/ilt20): ILT20 ball by ball since 2023: every International League T20 season. REST and MCP. MCP: https://mcp.yorkerapi.com/mcp/ilt20
- [The County Championship data API](https://yorkerapi.com/county): County Championship ball by ball since 2014: the County Championship, English first-class cricket. REST and MCP. MCP: https://mcp.yorkerapi.com/mcp/county
- [The WBBL data API](https://yorkerapi.com/wbbl): WBBL ball by ball since 2015: every Women's Big Bash League season. REST and MCP. MCP: https://mcp.yorkerapi.com/mcp/wbbl
- [The WPL data API](https://yorkerapi.com/wpl): WPL ball by ball since 2023: every Women's Premier League season. REST and MCP. MCP: https://mcp.yorkerapi.com/mcp/wpl
- [The Hundred (women) data API](https://yorkerapi.com/hundred-women): The Hundred (women) ball by ball since 2021: every women's season of The Hundred, with sportsbook prices from July 2026. REST and MCP. MCP: https://mcp.yorkerapi.com/mcp/hundred_women

### Datasets

- [Cricket ball-by-ball data](https://yorkerapi.com/data/cricket-ball-by-ball-api): Every delivery of 23,241 matches: Tests, ODIs, T20Is and the T20 leagues, men's and women's, with batter, bowler, runs, extras, wickets and fielders.
- [Cricket historical odds](https://yorkerapi.com/data/cricket-historical-odds-api): Match-winner prices by sportsbook from mid-2020, with line movement and in-play prices, on the same match ids as the ball-by-ball.

### Compared with the alternatives

- [Cricket data APIs compared: CricketData.org, Sportmonks, EntitySport and YorkerAPI](https://yorkerapi.com/compare/cricket-api): Cricket data APIs differ most in price, in whether ball-by-ball is included and in whether they carry odds. What each costs, and where YorkerAPI fits. (checked 2026-11-03)
- [Cricket MCP servers: the free options and YorkerAPI](https://yorkerapi.com/compare/cricket-mcp): The cricket MCP servers on GitHub are free wrappers you run yourself. What they cover, what they leave out, and when to use them instead of YorkerAPI. (checked 2026-11-03)

### Endpoint pages

- [get_schedule](https://yorkerapi.com/docs/get-schedule): Upcoming and live matches in every competition, with both sides' ratings
- [list_competitions](https://yorkerapi.com/docs/list-competitions): Every competition we hold with its key, format, match count and seasons
- [list_teams](https://yorkerapi.com/docs/list-teams): Team ids for international sides and franchises, men's and women's
- [get_matches](https://yorkerapi.com/docs/get-matches): Results by competition, season, team, venue or date, with scores and margins
- [get_match](https://yorkerapi.com/docs/get-match): One match in full: batting and bowling cards, ratings and every book's opening and closing price
- [get_deliveries](https://yorkerapi.com/docs/get-deliveries): Ball-by-ball rows for a match, a batter or a bowler, with our win probability
- [search_players](https://yorkerapi.com/docs/search-players): Find a player's id by name, or list a team's players
- [get_player](https://yorkerapi.com/docs/get-player): A career by format: runs, average, strike rate, wickets, economy, hundreds, best figures
- [get_player_stats](https://yorkerapi.com/docs/get-player-stats): A player split by season, competition, phase (powerplay, middle, death) or format
- [get_player_matches](https://yorkerapi.com/docs/get-player-matches): A player's matches with batting and bowling in each innings
- [get_matchup](https://yorkerapi.com/docs/get-matchup): A batter against a bowler: balls, runs, strike rate, dots and every dismissal
- [get_leaders](https://yorkerapi.com/docs/get-leaders): Leaders in runs, average, strike rate, sixes, wickets, economy
- [get_ratings](https://yorkerapi.com/docs/get-ratings): Our Elo ratings by format, best first
- [get_venue](https://yorkerapi.com/docs/get-venue): How a ground plays: par totals, batting first against chasing, toss effect
- [get_win_probability](https://yorkerapi.com/docs/get-win-probability): A match's win-probability worm over by over, and the balls that swung it
- [get_market_vs_model](https://yorkerapi.com/docs/get-market-vs-model): In-play prices beside our win probability, lined up to the exact ball
- [get_odds](https://yorkerapi.com/docs/get-odds): Match-winner prices by sportsbook, opening and closing, from mid-2020
- [get_line_movement](https://yorkerapi.com/docs/get-line-movement): Every pregame snapshot by book, the market line over time, and in-play prices

### Metric definitions

- [Yorker](https://yorkerapi.com/glossary/yorker): A delivery that lands on or just in front of the batter's crease, so it arrives at the feet or under the bat.
- [Economy rate](https://yorkerapi.com/glossary/economy-rate): The average number of runs a bowler concedes per over, the bowling counterpart of a run rate.
- [Strike rate](https://yorkerapi.com/glossary/strike-rate): For a batter, the runs scored per 100 balls faced. For a bowler, the balls bowled per wicket taken.
- [Powerplay](https://yorkerapi.com/glossary/powerplay): The opening stretch of a limited-overs innings in which only two fielders may stand outside the inner circle.
- [Duckworth-Lewis-Stern](https://yorkerapi.com/glossary/duckworth-lewis-stern): A method for setting a fair revised target when rain or bad light shortens a limited-overs match.
- [Maiden over](https://yorkerapi.com/glossary/maiden-over): An over in which the batting side scores no runs off the bowler.
- [Dot ball](https://yorkerapi.com/glossary/dot-ball): A legal delivery on which no run is scored, shown as a dot in the scorebook.
- [Net run rate](https://yorkerapi.com/glossary/net-run-rate): A team's run rate when batting minus the run rate it conceded, used to break ties on points in a league table.
- [Follow-on](https://yorkerapi.com/glossary/follow-on): In a multi-day match, the option for the side batting first to make the other side bat again after a big first-innings lead.
- [Batting average](https://yorkerapi.com/glossary/batting-average): The runs a batter has scored divided by the number of times they were dismissed.
- [Required run rate](https://yorkerapi.com/glossary/required-run-rate): The runs per over a chasing side still has to score to reach its target.
- [Super over](https://yorkerapi.com/glossary/super-over): A one-over-a-side tiebreaker used when a limited-overs match finishes level.

### By what you are building

- [Bettors and modellers](https://yorkerapi.com/for/bettors): Ball-by-ball for 23,241 matches joined to each sportsbook's match-winner price from mid-2020, in one id space.
- [Analysts and researchers](https://yorkerapi.com/for/analysts): 11.7 million deliveries from 2001, men's and women's, in every format, with a player id that follows each person across competitions.
- [Developers and AI builders](https://yorkerapi.com/for/developers): REST and MCP over the same data: matches, teams, players and every delivery, with stable ids.

### Code guides

Python, JavaScript and cURL for common questions, each run against the live API (code verified 2026-11-03). Index: https://yorkerapi.com/guides

- [How do I get cricket ball-by-ball data in Python?](https://yorkerapi.com/guides/cricket-ball-by-ball-python): Every delivery of a match: batter, bowler, runs, extras, the wicket and fielders, the score after the ball and our win probability. Tool: get_deliveries.
- [How do I get a batter's record against a bowler in Python?](https://yorkerapi.com/guides/cricket-batter-vs-bowler-python): Balls, runs, strike rate, dots, fours, sixes and every dismissal for one batter against one bowler, overall and by format. Tool: get_matchup.
- [How do I get a cricket win probability chart in Python?](https://yorkerapi.com/guides/cricket-win-probability-python): Our model's chance each side wins at the end of every over of a limited-overs match, and the ten balls that moved it most. Tool: get_win_probability.
- [How do I get historical cricket odds in Python?](https://yorkerapi.com/guides/cricket-historical-odds-python): Each sportsbook's opening and closing match-winner price for a match, from mid-2020, decimal and American. Tool: get_odds.
- [How do I compare in-play cricket odds with a win probability model?](https://yorkerapi.com/guides/cricket-market-vs-model-python): At each in-play price, the median margin-free price, our win probability after the last ball bowled before it, the score and the gap. Tool: get_market_vs_model.
- [How do I get every IPL match result in Python?](https://yorkerapi.com/guides/ipl-results-python): Every match of an IPL season with both scores, the toss, the result and the margin, one row per match. Tool: get_matches.
- [How do I get a batter's powerplay and death overs stats in Python?](https://yorkerapi.com/guides/cricket-powerplay-death-overs-python): A player's batting and bowling split by phase of the innings: powerplay, middle overs and death, counted from every ball. Tool: get_player_stats.
- [How do I find how a cricket ground plays in Python?](https://yorkerapi.com/guides/cricket-venue-toss-effect-python): Average first and second innings totals at a ground by format, how often the side batting first wins, what captains choose at the toss and how often the toss winner wins. Tool: get_venue.
- [How do I get cricket leaderboards in Python?](https://yorkerapi.com/guides/cricket-leaders-python): The top run scorers, wicket takers or best strike rates in a competition, season or format, counted from the balls. Tool: get_leaders.
- [How do I get cricket team ratings in Python?](https://yorkerapi.com/guides/cricket-team-ratings-python): Our Elo for every side in a format, best first, from results alone: Test sides, ODI sides, T20 franchises, men's or women's. Tool: get_ratings.