# Badminton API

> World badminton data as a JSON API and an MCP server: results and draws since 1899, players, rankings, venues, odds, ratings and analysis.

- [Full manual (Markdown)](https://badmintonapi.com/documentation/manual.md): every endpoint, parameter and field.
- [OpenAPI 3.1](https://badmintonapi.com/openapi.json): the whole API, machine-readable.
- [Documentation](https://badmintonapi.com/documentation)
- [Pricing](https://badmintonapi.com/pricing)
- MCP server: https://api.badmintonapi.com/mcp

## Endpoints

- `GET /v1/usage`: Your usage. Your key: plan, calls today and this month, limits and when they reset. Free to call. (Free key)
- `GET /v1/results/yesterday`: Yesterday's results. Every match finished yesterday (UTC), with scores and closing prices. (Free key)
- `GET /v1/results`: Results on a day. Matches finished on a day. The free key covers yesterday and today; Archive covers every day held. (Free key)
- `GET /v1/fixtures`: Fixtures. Matches scheduled next and those under way, soonest first. (Free key)
- `GET /v1/events/{id}`: One result or fixture. One match from the results and fixtures lists, by its ev_ id. (Free key)
- `GET /v1/series`: Series. The tournament series held, with their first and latest years. (Free key)
- `GET /v1/search`: Search. Find players, pairs, tournaments, series, countries, venues and cities by name, in one call. Accents and capitals do not matter; "Name / Name" finds both players of a pair; a year picks that edition. (Free key)
- `GET /v1/countries`: Countries. Every country with players held: players, active players, and titles by discipline. (Free key)
- `GET /v1/countries/{code}`: Country profile. One country by its IOC code: titles by discipline, its most successful players, recent titles and the editions it hosted. (Archive)
- `GET /v1/calendar`: Season calendar. A year's tournaments in date order, with dates, city, venue, prize money and whether each is finished, in progress or upcoming. (Free key)
- `GET /v1/venues`: Venues. Arenas that have staged tournaments held, most editions first, by country, city or name, with their height above sea level. (Archive)
- `GET /v1/venues/{id}`: Venue profile. One venue and every edition it staged, newest first. (Archive)
- `GET /v1/locations`: Host cities. Host cities, most editions first, with their venues and the years they staged tournaments. (Archive)
- `GET /v1/series/{slug}/champions`: Roll of honour. The roll of honour of a series: champions and runners-up in every event, year by year, with the players who won it most in meta. (Archive)
- `GET /v1/tournaments`: Tournaments. Tournament editions, newest first, with the disciplines and match counts of each. (Archive)
- `GET /v1/tournaments/{id}`: One tournament. One tournament edition, with its rounds by discipline and its podium: gold, silver and both bronzes in each event. (Archive)
- `GET /v1/tournaments/{id}/draw`: Tournament draw. A whole draw, first round to final, with seeds, scores and closing prices where held. (Archive)
- `GET /v1/tournaments/{id}/ties`: Ties. A team event (Thomas, Uber, Sudirman Cup): every tie with its nations, score, date and venue, and the matches inside it. (Archive)
- `GET /v1/matches`: Draw matches. Draw matches by player, tournament, series, year, discipline and round. (Archive)
- `GET /v1/matches/{id}`: One draw match. One draw match. (Archive)
- `GET /v1/players`: Players. Players by name, country (IOC code) and gender, most matches first. (Archive)
- `GET /v1/players/{id}`: Player profile. One player, with matches and wins by discipline, their best world ranking, and their birth date, playing hand and height where known. (Archive)
- `GET /v1/players/{id}/matches`: Player matches. A player's draw matches, newest first. (Archive)
- `GET /v1/players/{id}/partners`: Doubles partners. A player's doubles partners, most matches together first, with wins and titles as a pair. (Archive)
- `GET /v1/players/{id}/opponents`: Rivals. The players met most often, with wins and losses against each and the last meeting. (Archive)
- `GET /v1/players/{id}/titles`: Titles and finals. Every final a player reached, won or lost, newest first, with partner, opponents and score; totals by discipline in meta. (Archive)
- `GET /v1/players/{id}/form`: Form. A player's latest results, newest first, with the record over them and the winning or losing run they are on. (Archive)
- `GET /v1/players/{id}/stats`: Game statistics. Game statistics from every score held: games and points won, deciding games, extended games (20-all and beyond), comebacks after losing the first game, retirements. (Archive)
- `GET /v1/players/{id}/schedule`: Schedule load. How hard a player's calendar has been: each event played, newest first, with dates, matches, how far they went and the rest days before it; in meta, days since the last event, events and matches in the last 30 to 90 days and back-to-back weeks, as they stood on any day. (Archive)
- `GET /v1/players/{id}/rankings`: Ranking history. A player's world ranking over time, list by list, newest first: every list from September 2026, and the weekly top lists back to 2013 for weeks they were in them. (Archive)
- `GET /v1/h2h`: Head to head. Every meeting of two players, singles or doubles, with the wins of each. (Archive)
- `GET /v1/rankings`: World rankings. The world ranking for a discipline, the latest or as it stood on a date: every ranked player from September 2026, and for earlier dates back to 2013 the week's top list (about 20 to 25 places; meta.full says which). (Archive)
- `GET /v1/rankings/number-ones`: World number ones. Every world number one since the computer ranking began on 1 October 2009: each reign with its dates and weeks, by discipline, on a date, or for one player. (Archive)
- `GET /v1/ratings`: Our rating. Our own rating (Elo-style, from every senior result) as a table for a discipline on any date, or one player's rating history. Not an official BWF figure. (Archive)
- `GET /v1/predict`: Win chance. The chance each side wins from our rating, with a fair price and their head-to-head. Singles or doubles, on any date. (Odds)
- `GET /v1/analysis/upsets`: Biggest upsets. The biggest upsets: winners at the longest closing prices, or with the lowest chance by our rating. (Odds)
- `GET /v1/analysis/seeds`: How seeds perform. How seeds perform: for each seed, how often they reach the semi-final and final and win the title, and seeded against unseeded round by round. (Archive)
- `GET /v1/analysis/deciders`: Deciding games. How often matches go to a third game, how often the first-game loser wins, points per game and extended games, by decade or year. (Archive)
- `GET /v1/analysis/records`: Records. Records: most titles, most finals, longest winning runs, widest winning margins and most points in a match. (Archive)
- `GET /v1/analysis/market`: Market accuracy. How accurate the closing market is: favourites' expected and actual win rate by price band, by round and by seeding, the return at the closing price, and each bookmaker's average margin. (Odds)
- `GET /v1/odds/{id}`: Match odds. Opening and closing prices, bookmaker by bookmaker, for a draw match (mt_) or a results match (ev_): the match winner, and the handicap and total lines in games and points. (Odds)
- `GET /v1/backtest`: Backtest a strategy. Run a simple strategy over every settled match with closing prices: strike rate, return and how far it is from chance. (Odds)
- `GET /v1/live`: Live scores. Matches under way now, with the score so far. (Live)
- `GET /v1/live/stream`: Live stream. Live scores pushed to you as Server-Sent Events: every match in play on connect, then each match the moment its score, status or prices change, and a heartbeat every 15 seconds. A connection lasts about 5 minutes and counts as one call; reconnect when it ends (EventSource does by itself). Two streams at a time per key. (Live)
- `GET /v1/events/{id}/points`: Point by point. Point by point: every rally of a match, game by game, with the score after it, who won it and who served it, and each side's points won on and against serve and longest run. A match in play needs the Live plan. Rallies are being read for every finished match held, newest first. (Archive)

## Agent skill
- [Badminton API agent skill](https://badmintonapi.com/.well-known/agent-skills/badmintonapi/SKILL.md): how agents use Badminton API. Index: https://badmintonapi.com/.well-known/agent-skills/index.json