{"openapi":"3.1.0","info":{"title":"Badminton API","version":"1.45.20261010","description":"World badminton as JSON: results and draws since 1899, players, head to head, world rankings and world number ones, our own rating, odds, analysis and live scores. Every answer is {\"data\", \"meta\"}; times are UTC. Full guides: https://badmintonapi.com/documentation","contact":{"name":"Developer Data support","email":"support@developerdata.net","url":"https://badmintonapi.com/support"},"termsOfService":"https://badmintonapi.com/terms"},"servers":[{"url":"https://api.badmintonapi.com","description":"Production"}],"security":[{"bearer":[]},{"apiKey":[]}],"tags":[{"name":"Search and countries","description":"One search across every name, and every nation that plays."},{"name":"Results and calendar","description":"Yesterday, today, the fixtures ahead and the season's calendar."},{"name":"Tournaments and draws","description":"Every edition and every draw, first round to final, back to the first All England in 1899."},{"name":"Players","description":"Careers, partners, rivals, titles, form, game statistics and ranking history."},{"name":"Rankings and ratings","description":"The world ranking as published, and our own rating and win chance."},{"name":"Venues and cities","description":"The arena and city of every edition held."},{"name":"Odds and analysis","description":"Opening and closing prices, backtests, upsets, seeds, deciding games and records."},{"name":"Live","description":"Scores while the shuttle is in the air."},{"name":"Your key","description":"What your key can do, and what it has used."}],"paths":{"/v1/search":{"get":{"operationId":"search","summary":"Search","description":"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. Plan: Free key. MCP tool: search.","tags":["Search and countries"],"x-plan":"free","externalDocs":{"url":"https://badmintonapi.com/documentation/search"},"responses":{"200":{"description":"The answer: data, and meta with counts, pages and notes.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"kind":{"description":"player, tournament, series, country, venue or city."},"id":{"description":"The id: pl_, tr_, mt_, ev_ or vn_, never changing."},"name":{"description":"The name as held."},"country":{"description":"IOC country code, like DEN, or null."},"score":{"description":"How well the name matched, 30 to 100."}}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"example":{"request":"GET https://api.badmintonapi.com/v1/search?q=axelsen"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"q","in":"query","required":true,"description":"What to look for: \"axelsen\", \"lee chong wei\", \"all england 2023\", \"istora\".","schema":{"type":"string"}},{"name":"kind","in":"query","required":false,"description":"Only this kind: player, tournament, series, country, venue or city.","schema":{"type":"string","enum":["player","tournament","series","country","venue","city"]}},{"name":"limit","in":"query","required":false,"description":"Most results (for each player of a pair).","schema":{"type":"integer","minimum":1,"maximum":50,"default":10}}]}},"/v1/countries":{"get":{"operationId":"countries","summary":"Countries","description":"Every country with players held: players, active players, and titles by discipline. Plan: Free key. MCP tool: list_countries.","tags":["Search and countries"],"x-plan":"free","externalDocs":{"url":"https://badmintonapi.com/documentation/countries"},"responses":{"200":{"description":"The answer: data, and meta with counts, pages and notes.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"code":{"description":"The IOC country code, like DEN."},"name":{"description":"The name as held."},"players":{"description":"How many players are held for the country."},"active_players":{"description":"Players with a match in the last two years."},"first_year":{"description":"The first year a player from the country appears."},"titles":{"description":"Finals won."},"titles_by_discipline":{"description":"Titles in MS, WS, MD, WD and XD."}}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"example":{"request":"GET https://api.badmintonapi.com/v1/countries"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/countries/{code}":{"get":{"operationId":"country","summary":"Country profile","description":"One country by its IOC code: titles by discipline, its most successful players, recent titles and the editions it hosted. Plan: Archive. MCP tool: country_profile.","tags":["Search and countries"],"x-plan":"archive","externalDocs":{"url":"https://badmintonapi.com/documentation/country"},"responses":{"200":{"description":"The answer: data, and meta with counts, pages and notes.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","properties":{"code":{"description":"The IOC country code, like DEN."},"name":{"description":"The name as held."},"players":{"description":"How many players are held for the country."},"active_players":{"description":"Players with a match in the last two years."},"titles":{"description":"Finals won."},"titles_by_discipline":{"description":"Titles in MS, WS, MD, WD and XD."},"top_players":{"description":"The most successful players."},"recent_titles":{"description":"The latest titles, with players."},"hosted":{"description":"Editions staged, or hosted by a country."}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"example":{"request":"GET https://api.badmintonapi.com/v1/countries/DEN"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"code","in":"path","required":true,"description":"The country, like DEN.","schema":{"type":"string"}}]}},"/v1/results/yesterday":{"get":{"operationId":"resultsYesterday","summary":"Yesterday's results","description":"Every match finished yesterday (UTC), with scores and closing prices. Plan: Free key. MCP tool: yesterdays_results.","tags":["Results and calendar"],"x-plan":"free","externalDocs":{"url":"https://badmintonapi.com/documentation/results-yesterday"},"responses":{"200":{"description":"The answer: data, and meta with counts, pages and notes.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"description":"The id: pl_, tr_, mt_, ev_ or vn_, never changing."},"tournament":{"description":"The tournament: id, name and year."},"discipline":{"description":"MS, WS, MD, WD or XD."},"team_event":{"description":"True for a tie in a team event."},"start":{"description":"The first day or start time."},"status":{"description":"scheduled, live, finished; or finished, in_progress, upcoming."},"side1":{"description":"The first side: players and seed."},"side2":{"description":"The second side: players and seed."},"sets":{"description":"Games won by each side."},"games":{"description":"Game scores, like [[21,17],[19,21],[21,15]]; side 1 first unless stated."},"winner":{"description":"The winning side: 1 or 2, or its players."},"match":{"description":"The mt_ id of the draw match."},"odds":{"description":"Prices: bookmakers counted, opening, closing and best prices, the market's chance and margin. Odds plan."},"duration_min":{"description":"How long a finished match lasted, in minutes, from its start to its final point; null until it has finished, and for older matches whose record keeps no end time."}}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"example":{"request":"GET https://api.badmintonapi.com/v1/results/yesterday"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/results":{"get":{"operationId":"results","summary":"Results on a day","description":"Matches finished on a day. The free key covers yesterday and today; Archive covers every day held. Plan: Free key. MCP tool: results_on_date.","tags":["Results and calendar"],"x-plan":"free","externalDocs":{"url":"https://badmintonapi.com/documentation/results"},"responses":{"200":{"description":"The answer: data, and meta with counts, pages and notes.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"description":"The id: pl_, tr_, mt_, ev_ or vn_, never changing."},"tournament":{"description":"The tournament: id, name and year."},"discipline":{"description":"MS, WS, MD, WD or XD."},"team_event":{"description":"True for a tie in a team event."},"start":{"description":"The first day or start time."},"status":{"description":"scheduled, live, finished; or finished, in_progress, upcoming."},"side1":{"description":"The first side: players and seed."},"side2":{"description":"The second side: players and seed."},"sets":{"description":"Games won by each side."},"games":{"description":"Game scores, like [[21,17],[19,21],[21,15]]; side 1 first unless stated."},"winner":{"description":"The winning side: 1 or 2, or its players."},"match":{"description":"The mt_ id of the draw match."},"odds":{"description":"Prices: bookmakers counted, opening, closing and best prices, the market's chance and margin. Odds plan."},"duration_min":{"description":"How long a finished match lasted, in minutes, from its start to its final point; null until it has finished, and for older matches whose record keeps no end time."}}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"example":{"request":"GET https://api.badmintonapi.com/v1/results?date=2026-10-11"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"date","in":"query","required":true,"description":"The UTC day, YYYY-MM-DD.","schema":{"type":"string","format":"date"}},{"name":"discipline","in":"query","required":false,"description":"MS, WS, MD, WD or XD.","schema":{"type":"string","enum":["MS","WS","MD","WD","XD"]}},{"name":"page","in":"query","required":false,"description":"Which page.","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","required":false,"description":"Results a page, up to 200.","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"cursor","in":"query","required":false,"description":"Meta.next_cursor from the page before.","schema":{"type":"string"}}]}},"/v1/fixtures":{"get":{"operationId":"fixtures","summary":"Fixtures","description":"Matches scheduled next and those under way, soonest first. Plan: Free key. MCP tool: upcoming_matches.","tags":["Results and calendar"],"x-plan":"free","externalDocs":{"url":"https://badmintonapi.com/documentation/fixtures"},"responses":{"200":{"description":"The answer: data, and meta with counts, pages and notes.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"description":"The id: pl_, tr_, mt_, ev_ or vn_, never changing."},"tournament":{"description":"The tournament: id, name and year."},"discipline":{"description":"MS, WS, MD, WD or XD."},"team_event":{"description":"True for a tie in a team event."},"start":{"description":"The first day or start time."},"status":{"description":"scheduled, live, finished; or finished, in_progress, upcoming."},"side1":{"description":"The first side: players and seed."},"side2":{"description":"The second side: players and seed."},"sets":{"description":"Games won by each side."},"games":{"description":"Game scores, like [[21,17],[19,21],[21,15]]; side 1 first unless stated."},"winner":{"description":"The winning side: 1 or 2, or its players."},"match":{"description":"The mt_ id of the draw match."},"odds":{"description":"Prices: bookmakers counted, opening, closing and best prices, the market's chance and margin. Odds plan."},"duration_min":{"description":"How long a finished match lasted, in minutes, from its start to its final point; null until it has finished, and for older matches whose record keeps no end time."}}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"example":{"request":"GET https://api.badmintonapi.com/v1/fixtures"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"discipline","in":"query","required":false,"description":"MS, WS, MD, WD or XD.","schema":{"type":"string","enum":["MS","WS","MD","WD","XD"]}},{"name":"page","in":"query","required":false,"description":"Which page.","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","required":false,"description":"Results a page, up to 200.","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"cursor","in":"query","required":false,"description":"Meta.next_cursor from the page before.","schema":{"type":"string"}}]}},"/v1/events/{id}":{"get":{"operationId":"event","summary":"One result or fixture","description":"One match from the results and fixtures lists, by its ev_ id. Plan: Free key.","tags":["Results and calendar"],"x-plan":"free","externalDocs":{"url":"https://badmintonapi.com/documentation/event"},"responses":{"200":{"description":"The answer: data, and meta with counts, pages and notes.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","properties":{"id":{"description":"The id: pl_, tr_, mt_, ev_ or vn_, never changing."},"tournament":{"description":"The tournament: id, name and year."},"discipline":{"description":"MS, WS, MD, WD or XD."},"team_event":{"description":"True for a tie in a team event."},"start":{"description":"The first day or start time."},"status":{"description":"scheduled, live, finished; or finished, in_progress, upcoming."},"side1":{"description":"The first side: players and seed."},"side2":{"description":"The second side: players and seed."},"sets":{"description":"Games won by each side."},"games":{"description":"Game scores, like [[21,17],[19,21],[21,15]]; side 1 first unless stated."},"winner":{"description":"The winning side: 1 or 2, or its players."},"match":{"description":"The mt_ id of the draw match."},"odds":{"description":"Prices: bookmakers counted, opening, closing and best prices, the market's chance and margin. Odds plan."},"duration_min":{"description":"How long a finished match lasted, in minutes, from its start to its final point; null until it has finished, and for older matches whose record keeps no end time."}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"example":{"request":"GET https://api.badmintonapi.com/v1/events/ev_trk0gykq"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Which one, by its id.","schema":{"type":"string","description":"ev_ id"}}]}},"/v1/calendar":{"get":{"operationId":"calendar","summary":"Season calendar","description":"A year's tournaments in date order, with dates, city, venue, prize money and whether each is finished, in progress or upcoming. Plan: Free key. MCP tool: season_calendar.","tags":["Results and calendar"],"x-plan":"free","externalDocs":{"url":"https://badmintonapi.com/documentation/calendar"},"responses":{"200":{"description":"The answer: data, and meta with counts, pages and notes.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"description":"The id: pl_, tr_, mt_, ev_ or vn_, never changing."},"name":{"description":"The name as held."},"series":{"description":"The series, like all-england."},"level":{"description":"senior or junior."},"start":{"description":"The first day or start time."},"end":{"description":"The last day, YYYY-MM-DD, where known."},"city":{"description":"The host city."},"country":{"description":"IOC country code, like DEN, or null."},"venue":{"description":"The arena: id and name."},"prize_money":{"description":"Prize money as a whole number, as the record gives it."},"elevation_m":{"description":"Height above sea level in metres (the venue's own, else its host city's); null when not known. Shuttles fly faster in thinner air."},"status":{"description":"finished, in_progress, upcoming, or unknown when no dates are held."}}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"example":{"request":"GET https://api.badmintonapi.com/v1/calendar"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"year","in":"query","required":false,"description":"The season; this year when left out.","schema":{"type":"integer","minimum":1899}},{"name":"series","in":"query","required":false,"description":"A series from /v1/series.","schema":{"type":"string"}},{"name":"level","in":"query","required":false,"schema":{"type":"string","enum":["senior","junior","para"]}}]}},"/v1/series":{"get":{"operationId":"series","summary":"Series","description":"The tournament series held, with their first and latest years. Plan: Free key.","tags":["Tournaments and draws"],"x-plan":"free","externalDocs":{"url":"https://badmintonapi.com/documentation/series"},"responses":{"200":{"description":"The answer: data, and meta with counts, pages and notes.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"series":{"description":"The series, like all-england."},"name":{"description":"The series' name."},"level":{"description":"senior or junior."},"first_year":{"description":"The first year held."},"last_year":{"description":"The latest year held."},"editions":{"description":"How many tournament editions."}}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"example":{"request":"GET https://api.badmintonapi.com/v1/series"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/series/{slug}/champions":{"get":{"operationId":"seriesChampions","summary":"Roll of honour","description":"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. Plan: Archive. MCP tool: roll_of_honour.","tags":["Tournaments and draws"],"x-plan":"archive","externalDocs":{"url":"https://badmintonapi.com/documentation/series-champions"},"responses":{"200":{"description":"The answer: data, and meta with counts, pages and notes.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"year":{"description":"The year."},"tournament":{"description":"The edition: id and name."},"champions":{"description":"The winners in each discipline, with ids. Para badminton has one per sport class, keyed like \"MS WH1\"."},"runners_up":{"description":"The beaten finalists, keyed as champions are."}}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"example":{"request":"GET https://api.badmintonapi.com/v1/series/all-england/champions"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"slug","in":"path","required":true,"description":"The series, like all-england; the list is at /v1/series.","schema":{"type":"string"}},{"name":"discipline","in":"query","required":false,"description":"MS, WS, MD, WD or XD.","schema":{"type":"string","enum":["MS","WS","MD","WD","XD"]}}]}},"/v1/tournaments":{"get":{"operationId":"tournaments","summary":"Tournaments","description":"Tournament editions, newest first, with the disciplines and match counts of each. Plan: Archive. MCP tool: find_tournaments.","tags":["Tournaments and draws"],"x-plan":"archive","externalDocs":{"url":"https://badmintonapi.com/documentation/tournaments"},"responses":{"200":{"description":"The answer: data, and meta with counts, pages and notes.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"description":"The id: pl_, tr_, mt_, ev_ or vn_, never changing."},"series":{"description":"The series, like all-england."},"name":{"description":"The name as held."},"year":{"description":"The year."},"level":{"description":"senior or junior."},"disciplines":{"description":"The disciplines held."},"matches":{"description":"Matches played, or the matches themselves."}}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"example":{"request":"GET https://api.badmintonapi.com/v1/tournaments"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"series","in":"query","required":false,"description":"A series from /v1/series, like all-england.","schema":{"type":"string"}},{"name":"year","in":"query","required":false,"schema":{"type":"integer","minimum":1899}},{"name":"level","in":"query","required":false,"schema":{"type":"string","enum":["senior","junior","para"]}},{"name":"page","in":"query","required":false,"description":"Which page.","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","required":false,"description":"Results a page, up to 200.","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"cursor","in":"query","required":false,"description":"Meta.next_cursor from the page before.","schema":{"type":"string"}}]}},"/v1/tournaments/{id}":{"get":{"operationId":"tournament","summary":"One tournament","description":"One tournament edition, with its rounds by discipline and its podium: gold, silver and both bronzes in each event. Plan: Archive.","tags":["Tournaments and draws"],"x-plan":"archive","externalDocs":{"url":"https://badmintonapi.com/documentation/tournament"},"responses":{"200":{"description":"The answer: data, and meta with counts, pages and notes.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","properties":{"id":{"description":"The id: pl_, tr_, mt_, ev_ or vn_, never changing."},"series":{"description":"The series, like all-england."},"name":{"description":"The name as held."},"year":{"description":"The year."},"level":{"description":"senior or junior."},"disciplines":{"description":"The disciplines held."},"matches":{"description":"Matches played, or the matches themselves."},"rounds":{"description":"Matches in each round, by discipline."},"podium":{"description":"Each event's medallists: gold, silver and both bronzes (the losing semi-finalists), each a list of players with id, name and country; empty when the edition has no medal table."}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"example":{"request":"GET https://api.badmintonapi.com/v1/tournaments/tr_0574err6"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Which one, by its id.","schema":{"type":"string","description":"tr_ id"}}]}},"/v1/tournaments/{id}/draw":{"get":{"operationId":"draw","summary":"Tournament draw","description":"A whole draw, first round to final, with seeds, scores and closing prices where held. Plan: Archive. MCP tool: tournament_draw.","tags":["Tournaments and draws"],"x-plan":"archive","externalDocs":{"url":"https://badmintonapi.com/documentation/draw"},"responses":{"200":{"description":"The answer: data, and meta with counts, pages and notes.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"description":"The id: pl_, tr_, mt_, ev_ or vn_, never changing."},"tournament":{"description":"The tournament: id, name and year."},"discipline":{"description":"MS, WS, MD, WD or XD."},"round":{"description":"The round, as the draw names it, or its code."},"round_code":{"description":"R128, R64, R32, R16, QF, SF, 3P or F."},"sport_class":{"description":"Para badminton only: the sport class played, WH1, WH2, SL3, SL4, SU5 or SH6, or a pair such as WH1-WH2 for doubles; null otherwise."},"side1":{"description":"The first side: players and seed."},"side2":{"description":"The second side: players and seed."},"games":{"description":"Game scores, like [[21,17],[19,21],[21,15]]; side 1 first unless stated."},"winner":{"description":"The winning side: 1 or 2, or its players."},"outcome":{"description":"played, retired or walkover."},"event":{"description":"The ev_ id of the same match in the results feed, when linked."},"odds":{"description":"Prices: bookmakers counted, opening, closing and best prices, the market's chance and margin. Odds plan."}}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"example":{"request":"GET https://api.badmintonapi.com/v1/tournaments/tr_0574err6/draw?discipline=MS"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Which one, by its id.","schema":{"type":"string","description":"tr_ id"}},{"name":"discipline","in":"query","required":true,"description":"MS, WS, MD, WD or XD.","schema":{"type":"string","enum":["MS","WS","MD","WD","XD"]}},{"name":"sport_class","in":"query","required":false,"description":"Para badminton only: one sport class, like WH1 or SL3, or a pair, like WH1-WH2.","schema":{"type":"string"}}]}},"/v1/tournaments/{id}/ties":{"get":{"operationId":"ties","summary":"Ties","description":"A team event (Thomas, Uber, Sudirman Cup): every tie with its nations, score, date and venue, and the matches inside it. Plan: Archive. MCP tool: team_ties.","tags":["Tournaments and draws"],"x-plan":"archive","externalDocs":{"url":"https://badmintonapi.com/documentation/ties"},"responses":{"200":{"description":"The answer: data, and meta with counts, pages and notes.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"stage":{"description":"The stage, as named: Group A, Quarter-finals, Final."},"round_code":{"description":"QF, SF or F in the knockout stage; null in a group."},"number":{"description":"The tie's place on its page, in the order written."},"team1":{"description":"The first nation: code and name."},"team2":{"description":"The second nation: code and name."},"score":{"description":"Matches won by each nation, [3, 1]."},"winner":{"description":"The nation that won the tie: 1 or 2."},"date":{"description":"The day of the tie (YYYY-MM-DD), when known."},"venue":{"description":"Where the tie was played, as written (the hall, and the court when given)."},"matches":{"description":"The matches of the tie in order, each as /v1/matches gives it."}}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"example":{"request":"GET https://api.badmintonapi.com/v1/tournaments/tr_0574err6/ties"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Which one, by its id.","schema":{"type":"string","description":"tr_ id"}},{"name":"stage","in":"query","required":false,"description":"One stage only, as named: Group A, Quarter-finals, Final.","schema":{"type":"string"}}]}},"/v1/matches":{"get":{"operationId":"matches","summary":"Draw matches","description":"Draw matches by player, tournament, series, year, discipline and round. Plan: Archive. MCP tool: find_matches.","tags":["Tournaments and draws"],"x-plan":"archive","externalDocs":{"url":"https://badmintonapi.com/documentation/matches"},"responses":{"200":{"description":"The answer: data, and meta with counts, pages and notes.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"description":"The id: pl_, tr_, mt_, ev_ or vn_, never changing."},"tournament":{"description":"The tournament: id, name and year."},"discipline":{"description":"MS, WS, MD, WD or XD."},"round":{"description":"The round, as the draw names it, or its code."},"round_code":{"description":"R128, R64, R32, R16, QF, SF, 3P or F."},"sport_class":{"description":"Para badminton only: the sport class played, WH1, WH2, SL3, SL4, SU5 or SH6, or a pair such as WH1-WH2 for doubles; null otherwise."},"side1":{"description":"The first side: players and seed."},"side2":{"description":"The second side: players and seed."},"games":{"description":"Game scores, like [[21,17],[19,21],[21,15]]; side 1 first unless stated."},"winner":{"description":"The winning side: 1 or 2, or its players."},"outcome":{"description":"played, retired or walkover."},"event":{"description":"The ev_ id of the same match in the results feed, when linked."},"odds":{"description":"Prices: bookmakers counted, opening, closing and best prices, the market's chance and margin. Odds plan."}}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"example":{"request":"GET https://api.badmintonapi.com/v1/matches"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"player","in":"query","required":false,"schema":{"type":"string","description":"pl_ id"}},{"name":"tournament","in":"query","required":false,"schema":{"type":"string","description":"tr_ id"}},{"name":"series","in":"query","required":false,"schema":{"type":"string"}},{"name":"year","in":"query","required":false,"schema":{"type":"integer","minimum":1899}},{"name":"discipline","in":"query","required":false,"description":"MS, WS, MD, WD or XD.","schema":{"type":"string","enum":["MS","WS","MD","WD","XD"]}},{"name":"round","in":"query","required":false,"description":"R128, R64, R32, R16, QF, SF, 3P or F.","schema":{"type":"string","enum":["R128","R64","R32","R16","QF","SF","3P","F"]}},{"name":"with_odds","in":"query","required":false,"description":"True for matches with closing prices only.","schema":{"type":"boolean"}},{"name":"page","in":"query","required":false,"description":"Which page.","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","required":false,"description":"Results a page, up to 200.","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"cursor","in":"query","required":false,"description":"Meta.next_cursor from the page before.","schema":{"type":"string"}}]}},"/v1/matches/{id}":{"get":{"operationId":"match","summary":"One draw match","description":"One draw match. Plan: Archive.","tags":["Tournaments and draws"],"x-plan":"archive","externalDocs":{"url":"https://badmintonapi.com/documentation/match"},"responses":{"200":{"description":"The answer: data, and meta with counts, pages and notes.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","properties":{"id":{"description":"The id: pl_, tr_, mt_, ev_ or vn_, never changing."},"tournament":{"description":"The tournament: id, name and year."},"discipline":{"description":"MS, WS, MD, WD or XD."},"round":{"description":"The round, as the draw names it, or its code."},"round_code":{"description":"R128, R64, R32, R16, QF, SF, 3P or F."},"sport_class":{"description":"Para badminton only: the sport class played, WH1, WH2, SL3, SL4, SU5 or SH6, or a pair such as WH1-WH2 for doubles; null otherwise."},"side1":{"description":"The first side: players and seed."},"side2":{"description":"The second side: players and seed."},"games":{"description":"Game scores, like [[21,17],[19,21],[21,15]]; side 1 first unless stated."},"winner":{"description":"The winning side: 1 or 2, or its players."},"outcome":{"description":"played, retired or walkover."},"event":{"description":"The ev_ id of the same match in the results feed, when linked."},"odds":{"description":"Prices: bookmakers counted, opening, closing and best prices, the market's chance and margin. Odds plan."}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"example":{"request":"GET https://api.badmintonapi.com/v1/matches/mt_3bt85wzp"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Which one, by its id.","schema":{"type":"string","description":"mt_ id"}}]}},"/v1/players":{"get":{"operationId":"players","summary":"Players","description":"Players by name, country (IOC code) and gender, most matches first. Plan: Archive. MCP tool: find_player.","tags":["Players"],"x-plan":"archive","externalDocs":{"url":"https://badmintonapi.com/documentation/players"},"responses":{"200":{"description":"The answer: data, and meta with counts, pages and notes.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"description":"The id: pl_, tr_, mt_, ev_ or vn_, never changing."},"name":{"description":"The name as held."},"slug":{"description":"The name in a web address."},"country":{"description":"IOC country code, like DEN, or null."},"gender":{"description":"M or W, from the events played."},"first_year":{"description":"The first year held."},"last_year":{"description":"The latest year held."},"matches":{"description":"Draw matches played."},"wins":{"description":"Matches won."}}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"example":{"request":"GET https://api.badmintonapi.com/v1/players"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"q","in":"query","required":false,"description":"Part of a name.","schema":{"type":"string"}},{"name":"country","in":"query","required":false,"description":"IOC code, like DEN.","schema":{"type":"string"}},{"name":"gender","in":"query","required":false,"schema":{"type":"string","enum":["M","W"]}},{"name":"page","in":"query","required":false,"description":"Which page.","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","required":false,"description":"Results a page, up to 200.","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"cursor","in":"query","required":false,"description":"Meta.next_cursor from the page before.","schema":{"type":"string"}}]}},"/v1/players/{id}":{"get":{"operationId":"player","summary":"Player profile","description":"One player, with matches and wins by discipline, their best world ranking, and their birth date, playing hand and height where known. Plan: Archive.","tags":["Players"],"x-plan":"archive","externalDocs":{"url":"https://badmintonapi.com/documentation/player"},"responses":{"200":{"description":"The answer: data, and meta with counts, pages and notes.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","properties":{"id":{"description":"The id: pl_, tr_, mt_, ev_ or vn_, never changing."},"name":{"description":"The name as held."},"slug":{"description":"The name in a web address."},"country":{"description":"IOC country code, like DEN, or null."},"gender":{"description":"M or W, from the events played."},"first_year":{"description":"The first year held."},"last_year":{"description":"The latest year held."},"matches":{"description":"Draw matches played."},"wins":{"description":"Matches won."},"by_discipline":{"description":"The same figures split by MS, WS, MD, WD and XD."},"career_high":{"description":"The player's best world ranking: rank, discipline, date (YYYY-MM-DD, or YYYY-MM when only the month is known) and doubles partner, with the best in each other event in other_events; null when none is known."},"number_one":{"description":"Time at world number one since 1 October 2009, by discipline: weeks in all, reigns, first and last day (last is null while it goes on) and current; null for a player who never was."},"born":{"description":"The player's birth date, YYYY-MM-DD; null when not known."},"hand":{"description":"The hand the player plays with: left or right; null when not known."},"height_cm":{"description":"The player's height in centimetres; null when not known."},"coach":{"description":"The player's coach or coaches as their own page names them, comma separated; null when not known."}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"example":{"request":"GET https://api.badmintonapi.com/v1/players/pl_9k1rzjad"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Which one, by its id.","schema":{"type":"string","description":"pl_ id"}}]}},"/v1/players/{id}/matches":{"get":{"operationId":"playerMatches","summary":"Player matches","description":"A player's draw matches, newest first. Plan: Archive. MCP tool: player_matches.","tags":["Players"],"x-plan":"archive","externalDocs":{"url":"https://badmintonapi.com/documentation/player-matches"},"responses":{"200":{"description":"The answer: data, and meta with counts, pages and notes.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"description":"The id: pl_, tr_, mt_, ev_ or vn_, never changing."},"tournament":{"description":"The tournament: id, name and year."},"discipline":{"description":"MS, WS, MD, WD or XD."},"round":{"description":"The round, as the draw names it, or its code."},"round_code":{"description":"R128, R64, R32, R16, QF, SF, 3P or F."},"sport_class":{"description":"Para badminton only: the sport class played, WH1, WH2, SL3, SL4, SU5 or SH6, or a pair such as WH1-WH2 for doubles; null otherwise."},"side1":{"description":"The first side: players and seed."},"side2":{"description":"The second side: players and seed."},"games":{"description":"Game scores, like [[21,17],[19,21],[21,15]]; side 1 first unless stated."},"winner":{"description":"The winning side: 1 or 2, or its players."},"outcome":{"description":"played, retired or walkover."},"event":{"description":"The ev_ id of the same match in the results feed, when linked."},"odds":{"description":"Prices: bookmakers counted, opening, closing and best prices, the market's chance and margin. Odds plan."}}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"example":{"request":"GET https://api.badmintonapi.com/v1/players/pl_9k1rzjad/matches"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Which one, by its id.","schema":{"type":"string","description":"pl_ id"}},{"name":"year","in":"query","required":false,"schema":{"type":"integer","minimum":1899}},{"name":"discipline","in":"query","required":false,"description":"MS, WS, MD, WD or XD.","schema":{"type":"string","enum":["MS","WS","MD","WD","XD"]}},{"name":"page","in":"query","required":false,"description":"Which page.","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","required":false,"description":"Results a page, up to 200.","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"cursor","in":"query","required":false,"description":"Meta.next_cursor from the page before.","schema":{"type":"string"}}]}},"/v1/players/{id}/partners":{"get":{"operationId":"playerPartners","summary":"Doubles partners","description":"A player's doubles partners, most matches together first, with wins and titles as a pair. Plan: Archive. MCP tool: player_partners.","tags":["Players"],"x-plan":"archive","externalDocs":{"url":"https://badmintonapi.com/documentation/player-partners"},"responses":{"200":{"description":"The answer: data, and meta with counts, pages and notes.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"partner":{"description":"The doubles partner, or null in singles."},"discipline":{"description":"MS, WS, MD, WD or XD."},"matches":{"description":"Matches played together."},"wins":{"description":"Matches won together."},"titles":{"description":"Titles won together."},"first_year":{"description":"The first year held."},"last_year":{"description":"The latest year held."}}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"example":{"request":"GET https://api.badmintonapi.com/v1/players/pl_9k1rzjad/partners"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Which one, by its id.","schema":{"type":"string","description":"pl_ id"}},{"name":"discipline","in":"query","required":false,"description":"MS, WS, MD, WD or XD.","schema":{"type":"string","enum":["MS","WS","MD","WD","XD"]}}]}},"/v1/players/{id}/opponents":{"get":{"operationId":"playerOpponents","summary":"Rivals","description":"The players met most often, with wins and losses against each and the last meeting. Plan: Archive. MCP tool: player_opponents.","tags":["Players"],"x-plan":"archive","externalDocs":{"url":"https://badmintonapi.com/documentation/player-opponents"},"responses":{"200":{"description":"The answer: data, and meta with counts, pages and notes.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"opponent":{"description":"The player met."},"meetings":{"description":"Times they met."},"wins":{"description":"Meetings this player won."},"losses":{"description":"Meetings this player lost."},"last":{"description":"The most recent meeting, with score."}}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"example":{"request":"GET https://api.badmintonapi.com/v1/players/pl_9k1rzjad/opponents"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Which one, by its id.","schema":{"type":"string","description":"pl_ id"}},{"name":"discipline","in":"query","required":false,"description":"MS, WS, MD, WD or XD.","schema":{"type":"string","enum":["MS","WS","MD","WD","XD"]}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}]}},"/v1/players/{id}/titles":{"get":{"operationId":"playerTitles","summary":"Titles and finals","description":"Every final a player reached, won or lost, newest first, with partner, opponents and score; totals by discipline in meta. Plan: Archive. MCP tool: player_titles.","tags":["Players"],"x-plan":"archive","externalDocs":{"url":"https://badmintonapi.com/documentation/player-titles"},"responses":{"200":{"description":"The answer: data, and meta with counts, pages and notes.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"result":{"description":"W or L, or won or runner_up."},"tournament":{"description":"The tournament: id, name and year."},"level":{"description":"senior or junior."},"discipline":{"description":"MS, WS, MD, WD or XD."},"sport_class":{"description":"Para badminton only: the sport class played, WH1, WH2, SL3, SL4, SU5 or SH6, or a pair such as WH1-WH2 for doubles; null otherwise."},"partner":{"description":"The doubles partner, or null in singles."},"opponents":{"description":"The other side's players."},"games":{"description":"Game scores from this player's side."},"match":{"description":"The mt_ id of the draw match."}}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"example":{"request":"GET https://api.badmintonapi.com/v1/players/pl_9k1rzjad/titles"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Which one, by its id.","schema":{"type":"string","description":"pl_ id"}},{"name":"discipline","in":"query","required":false,"description":"MS, WS, MD, WD or XD.","schema":{"type":"string","enum":["MS","WS","MD","WD","XD"]}}]}},"/v1/players/{id}/form":{"get":{"operationId":"playerForm","summary":"Form","description":"A player's latest results, newest first, with the record over them and the winning or losing run they are on. Plan: Archive. MCP tool: player_form.","tags":["Players"],"x-plan":"archive","externalDocs":{"url":"https://badmintonapi.com/documentation/player-form"},"responses":{"200":{"description":"The answer: data, and meta with counts, pages and notes.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"result":{"description":"W or L, or won or runner_up."},"tournament":{"description":"The tournament: id, name and year."},"date":{"description":"The day, YYYY-MM-DD."},"discipline":{"description":"MS, WS, MD, WD or XD."},"round":{"description":"The round, as the draw names it, or its code."},"opponents":{"description":"The other side's players."},"games":{"description":"Game scores from this player's side."},"outcome":{"description":"played, retired or walkover."},"match":{"description":"The mt_ id of the draw match."}}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"example":{"request":"GET https://api.badmintonapi.com/v1/players/pl_9k1rzjad/form"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Which one, by its id.","schema":{"type":"string","description":"pl_ id"}},{"name":"discipline","in":"query","required":false,"description":"MS, WS, MD, WD or XD.","schema":{"type":"string","enum":["MS","WS","MD","WD","XD"]}},{"name":"last","in":"query","required":false,"description":"How many matches.","schema":{"type":"integer","minimum":1,"maximum":50,"default":10}}]}},"/v1/players/{id}/stats":{"get":{"operationId":"playerStats","summary":"Game statistics","description":"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. Plan: Archive. MCP tool: player_stats.","tags":["Players"],"x-plan":"archive","externalDocs":{"url":"https://badmintonapi.com/documentation/player-stats"},"responses":{"200":{"description":"The answer: data, and meta with counts, pages and notes.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"player":{"description":"The player: id, name and country."},"filters":{"description":"The filters applied."},"matches":{"description":"Matches played, or the matches themselves."},"wins":{"description":"Matches won."},"win_rate":{"description":"Share of matches won."},"game_win_rate":{"description":"Share of games won."},"point_share":{"description":"Share of all points won."},"deciding_games":{"description":"Three-game matches: played, won, rate."},"extended_games":{"description":"Games where the loser reached 20 (21-point scoring, 2006 on): played, won, rate."},"after_losing_first_game":{"description":"Matches after losing the first game: played, won, rate."},"after_winning_first_game":{"description":"Matches after winning the first game: played, won, rate."},"retirements":{"description":"Matches won or lost by retirement."},"walkovers":{"description":"Matches given or conceded without play."},"by_discipline":{"description":"The same figures split by MS, WS, MD, WD and XD."}}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"example":{"request":"GET https://api.badmintonapi.com/v1/players/pl_9k1rzjad/stats"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Which one, by its id.","schema":{"type":"string","description":"pl_ id"}},{"name":"discipline","in":"query","required":false,"description":"MS, WS, MD, WD or XD.","schema":{"type":"string","enum":["MS","WS","MD","WD","XD"]}},{"name":"from","in":"query","required":false,"schema":{"type":"integer","minimum":1899}},{"name":"to","in":"query","required":false,"schema":{"type":"integer","minimum":1899}}]}},"/v1/players/{id}/schedule":{"get":{"operationId":"playerSchedule","summary":"Schedule load","description":"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. Plan: Archive. MCP tool: player_schedule.","tags":["Players"],"x-plan":"archive","externalDocs":{"url":"https://badmintonapi.com/documentation/player-schedule"},"responses":{"200":{"description":"The answer: data, and meta with counts, pages and notes.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"tournament":{"description":"The tournament: id, name and year."},"level":{"description":"senior or junior."},"start":{"description":"The first day or start time."},"end":{"description":"The last day, YYYY-MM-DD, where known."},"disciplines":{"description":"The disciplines held."},"matches":{"description":"Matches played, or the matches themselves."},"wins":{"description":"Matches won."},"furthest":{"description":"The furthest round reached: F, SF, QF, R16, R32, R64 or R128."},"title":{},"rest_days":{"description":"Free days between the end of the player's previous event and the start of this one; null for their first."},"back_to_back":{"description":"True when this event started within a week of the previous one ending: no free week between."},"week_run":{"description":"How many events in a row, ending with this one, were played back to back."}}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"example":{"request":"GET https://api.badmintonapi.com/v1/players/pl_9k1rzjad/schedule"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Which one, by its id.","schema":{"type":"string","description":"pl_ id"}},{"name":"discipline","in":"query","required":false,"description":"MS, WS, MD, WD or XD.","schema":{"type":"string","enum":["MS","WS","MD","WD","XD"]}},{"name":"date","in":"query","required":false,"description":"The day to measure from, YYYY-MM-DD (default today); later events are left out.","schema":{"type":"string","format":"date"}},{"name":"last","in":"query","required":false,"description":"How many events.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}]}},"/v1/players/{id}/rankings":{"get":{"operationId":"playerRankings","summary":"Ranking history","description":"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. Plan: Archive. MCP tool: player_ranking_history.","tags":["Players"],"x-plan":"archive","externalDocs":{"url":"https://badmintonapi.com/documentation/player-rankings"},"responses":{"200":{"description":"The answer: data, and meta with counts, pages and notes.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"date":{"description":"The day, YYYY-MM-DD."},"discipline":{"description":"MS, WS, MD, WD or XD."},"rank":{"description":"Position in the list."},"points":{"description":"Ranking points."}}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"example":{"request":"GET https://api.badmintonapi.com/v1/players/pl_9k1rzjad/rankings"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Which one, by its id.","schema":{"type":"string","description":"pl_ id"}},{"name":"discipline","in":"query","required":false,"description":"MS, WS, MD, WD or XD.","schema":{"type":"string","enum":["MS","WS","MD","WD","XD"]}}]}},"/v1/h2h":{"get":{"operationId":"headToHead","summary":"Head to head","description":"Every meeting of two players, singles or doubles, with the wins of each. Plan: Archive. MCP tool: head_to_head.","tags":["Players"],"x-plan":"archive","externalDocs":{"url":"https://badmintonapi.com/documentation/head-to-head"},"responses":{"200":{"description":"The answer: data, and meta with counts, pages and notes.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","properties":{"player1":{"description":"The first player and their wins."},"player2":{"description":"The second player and their wins."},"meetings":{"description":"Times they met."},"matches":{"description":"Matches played, or the matches themselves."}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"example":{"request":"GET https://api.badmintonapi.com/v1/h2h?player1=pl_9k1rzjad&player2=pl_hmfabfyf"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"player1","in":"query","required":true,"schema":{"type":"string","description":"pl_ id"}},{"name":"player2","in":"query","required":true,"schema":{"type":"string","description":"pl_ id"}}]}},"/v1/rankings":{"get":{"operationId":"rankings","summary":"World rankings","description":"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). Plan: Archive. MCP tool: world_rankings.","tags":["Rankings and ratings"],"x-plan":"archive","externalDocs":{"url":"https://badmintonapi.com/documentation/rankings"},"responses":{"200":{"description":"The answer: data, and meta with counts, pages and notes.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"rank":{"description":"Position in the list."},"name":{"description":"The entry: a player, or both players of a doubles pair."},"players":{"description":"The entry's players: id (null when not yet matched to a player), name and country."},"points":{"description":"Ranking points."}}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"example":{"request":"GET https://api.badmintonapi.com/v1/rankings?discipline=MS"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"discipline","in":"query","required":true,"description":"MS, WS, MD, WD or XD.","schema":{"type":"string","enum":["MS","WS","MD","WD","XD"]}},{"name":"date","in":"query","required":false,"description":"The ranking in force on this day.","schema":{"type":"string","format":"date"}},{"name":"page","in":"query","required":false,"description":"Which page.","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","required":false,"description":"Results a page, up to 200.","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"cursor","in":"query","required":false,"description":"Meta.next_cursor from the page before.","schema":{"type":"string"}}]}},"/v1/rankings/number-ones":{"get":{"operationId":"numberOnes","summary":"World number ones","description":"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. Plan: Archive. MCP tool: world_number_ones.","tags":["Rankings and ratings"],"x-plan":"archive","externalDocs":{"url":"https://badmintonapi.com/documentation/number-ones"},"responses":{"200":{"description":"The answer: data, and meta with counts, pages and notes.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"discipline":{"description":"MS, WS, MD, WD or XD."},"start":{"description":"The first ranking day of the reign, YYYY-MM-DD."},"end":{"description":"The last ranking day of the reign, YYYY-MM-DD; null while it goes on."},"weeks":{"description":"Weeks in this reign, as the reign is counted."},"current":{"description":"True for the reign still going."},"players":{"description":"The number one: one player in singles, both partners in doubles, each with id (null when not in the draws), name and country."}}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"example":{"request":"GET https://api.badmintonapi.com/v1/rankings/number-ones"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"discipline","in":"query","required":false,"description":"MS, WS, MD, WD or XD.","schema":{"type":"string","enum":["MS","WS","MD","WD","XD"]}},{"name":"date","in":"query","required":false,"description":"Only the reign in force on this day.","schema":{"type":"string","format":"date"}},{"name":"player","in":"query","required":false,"description":"Only this player's reigns.","schema":{"type":"string","description":"pl_ id"}}]}},"/v1/ratings":{"get":{"operationId":"ratings","summary":"Our rating","description":"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. Plan: Archive. MCP tool: player_ratings.","tags":["Rankings and ratings"],"x-plan":"archive","externalDocs":{"url":"https://badmintonapi.com/documentation/ratings"},"responses":{"200":{"description":"The answer: data, and meta with counts, pages and notes.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"rank":{"description":"Position in the list."},"player":{"description":"The player: id, name and country."},"rating":{"description":"Our rating, starting at 1500."},"matches":{"description":"Matches played, or the matches themselves."},"last_rated":{"description":"The last day of the edition in which the rating last changed (for an edition still under way, the day it is due to end)."}}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"example":{"request":"GET https://api.badmintonapi.com/v1/ratings"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"discipline","in":"query","required":false,"description":"MS, WS, MD, WD or XD.","schema":{"type":"string","enum":["MS","WS","MD","WD","XD"]}},{"name":"date","in":"query","required":false,"description":"The ratings as they stood that day; today when left out.","schema":{"type":"string","format":"date"}},{"name":"player","in":"query","required":false,"description":"One player's history instead of a table.","schema":{"type":"string","description":"pl_ id"}},{"name":"active","in":"query","required":false,"description":"Only players rated in the year before the date (default true).","schema":{"type":"boolean"}},{"name":"page","in":"query","required":false,"description":"Which page.","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","required":false,"description":"Results a page, up to 200.","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"cursor","in":"query","required":false,"description":"Meta.next_cursor from the page before.","schema":{"type":"string"}}]}},"/v1/predict":{"get":{"operationId":"predict","summary":"Win chance","description":"The chance each side wins from our rating, with a fair price and their head-to-head. Singles or doubles, on any date. Plan: Odds. MCP tool: win_chance.","tags":["Rankings and ratings"],"x-plan":"odds","externalDocs":{"url":"https://badmintonapi.com/documentation/predict"},"responses":{"200":{"description":"The answer: data, and meta with counts, pages and notes.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","properties":{"discipline":{"description":"MS, WS, MD, WD or XD."},"date":{"description":"The day, YYYY-MM-DD."},"host":{"description":"The host given: code, and home_side (1 or 2, the side whose players are all from it; null when neither or both)."},"side1":{"description":"Side 1: players, rating, continent (the one its players share, else null), chance and fair price."},"side2":{"description":"Side 2: players, rating, continent, chance and fair price."},"head_to_head":{"description":"Meetings between the two sides and the wins of each."},"age_gap_years":{"description":"Singles: how many years older side 2 is than side 1 on the date (below 0 when side 1 is older), when both birth dates are known; the chance includes the age term (meta.model.age). Null in doubles or when a date is missing."},"decider":{"description":"With games at one game all: each side's chance of the deciding game (side1, side2), fair_price for each, which side won the second game and by how many points; null without games."}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"example":{"request":"GET https://api.badmintonapi.com/v1/predict?player1=pl_9k1rzjad&player2=pl_hmfabfyf"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"player1","in":"query","required":true,"schema":{"type":"string","description":"pl_ id"}},{"name":"player2","in":"query","required":true,"schema":{"type":"string","description":"pl_ id"}},{"name":"partner1","in":"query","required":false,"description":"Doubles: player1's partner.","schema":{"type":"string","description":"pl_ id"}},{"name":"partner2","in":"query","required":false,"description":"Doubles: player2's partner.","schema":{"type":"string","description":"pl_ id"}},{"name":"discipline","in":"query","required":false,"description":"MS, WS, MD, WD or XD.","schema":{"type":"string","enum":["MS","WS","MD","WD","XD"]}},{"name":"date","in":"query","required":false,"description":"The ratings as they stood that day.","schema":{"type":"string","format":"date"}},{"name":"host","in":"query","required":false,"description":"The host country's IOC code, like DEN: a side whose players are all from it is moved by the home figure in meta.model.home_edge (rating points; null when testing found none, and it can be below 0).","schema":{"type":"string"}},{"name":"games","in":"query","required":false,"description":"In play at one game all: the first two games from side 1, like 21-15,18-21; adds the chance of the deciding game.","schema":{"type":"string"}}]}},"/v1/venues":{"get":{"operationId":"venues","summary":"Venues","description":"Arenas that have staged tournaments held, most editions first, by country, city or name, with their height above sea level. Plan: Archive. MCP tool: find_venues.","tags":["Venues and cities"],"x-plan":"archive","externalDocs":{"url":"https://badmintonapi.com/documentation/venues"},"responses":{"200":{"description":"The answer: data, and meta with counts, pages and notes.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"description":"The id: pl_, tr_, mt_, ev_ or vn_, never changing."},"name":{"description":"The name as held."},"city":{"description":"The host city."},"country":{"description":"IOC country code, like DEN, or null."},"editions":{"description":"Editions staged there."},"first_year":{"description":"The first year held."},"last_year":{"description":"The latest year held."},"elevation_m":{"description":"Height above sea level in metres (the venue's own, else its host city's); null when not known. Shuttles fly faster in thinner air."},"elevation_from":{"description":"Where elevation_m comes from: venue (its own height) or city (the host city's); null when not known."}}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"example":{"request":"GET https://api.badmintonapi.com/v1/venues"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"country","in":"query","required":false,"description":"IOC code, like INA.","schema":{"type":"string"}},{"name":"city","in":"query","required":false,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"Part of the venue name.","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Which page.","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","required":false,"description":"Results a page, up to 200.","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"cursor","in":"query","required":false,"description":"Meta.next_cursor from the page before.","schema":{"type":"string"}}]}},"/v1/venues/{id}":{"get":{"operationId":"venue","summary":"Venue profile","description":"One venue and every edition it staged, newest first. Plan: Archive.","tags":["Venues and cities"],"x-plan":"archive","externalDocs":{"url":"https://badmintonapi.com/documentation/venue"},"responses":{"200":{"description":"The answer: data, and meta with counts, pages and notes.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","properties":{"id":{"description":"The id: pl_, tr_, mt_, ev_ or vn_, never changing."},"name":{"description":"The name as held."},"city":{"description":"The host city."},"country":{"description":"IOC country code, like DEN, or null."},"editions":{"description":"Editions staged there."},"first_year":{"description":"The first year held."},"last_year":{"description":"The latest year held."},"elevation_m":{"description":"Height above sea level in metres (the venue's own, else its host city's); null when not known. Shuttles fly faster in thinner air."},"elevation_from":{"description":"Where elevation_m comes from: venue (its own height) or city (the host city's); null when not known."},"hosted":{"description":"Editions staged, or hosted by a country."}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"example":{"request":"GET https://api.badmintonapi.com/v1/venues/vn_957y5h4h"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Which one, by its id.","schema":{"type":"string","description":"vn_ id"}}]}},"/v1/locations":{"get":{"operationId":"locations","summary":"Host cities","description":"Host cities, most editions first, with their venues and the years they staged tournaments. Plan: Archive. MCP tool: host_cities.","tags":["Venues and cities"],"x-plan":"archive","externalDocs":{"url":"https://badmintonapi.com/documentation/locations"},"responses":{"200":{"description":"The answer: data, and meta with counts, pages and notes.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"city":{"description":"The host city."},"country":{"description":"IOC country code, like DEN, or null."},"country_name":{"description":"The country's name."},"editions":{"description":"Editions staged in the city."},"venues":{"description":"How many venues in the city."},"first_year":{"description":"The first year held."},"last_year":{"description":"The latest year held."}}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"example":{"request":"GET https://api.badmintonapi.com/v1/locations"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"country","in":"query","required":false,"description":"IOC code, like ENG.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"Part of the city name.","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Which page.","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","required":false,"description":"Results a page, up to 200.","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"cursor","in":"query","required":false,"description":"Meta.next_cursor from the page before.","schema":{"type":"string"}}]}},"/v1/analysis/upsets":{"get":{"operationId":"upsets","summary":"Biggest upsets","description":"The biggest upsets: winners at the longest closing prices, or with the lowest chance by our rating. Plan: Odds. MCP tool: biggest_upsets.","tags":["Odds and analysis"],"x-plan":"odds","externalDocs":{"url":"https://badmintonapi.com/documentation/upsets"},"responses":{"200":{"description":"The answer: data, and meta with counts, pages and notes.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"match":{"description":"The mt_ id of the draw match."},"tournament":{"description":"The tournament: id, name and year."},"discipline":{"description":"MS, WS, MD, WD or XD."},"round":{"description":"The round, as the draw names it, or its code."},"winner":{"description":"The winning side: 1 or 2, or its players."},"loser":{"description":"The losing side's players."},"games":{"description":"Game scores from the winner's side."},"winner_price":{"description":"The winner's average closing price."},"winner_chance":{"description":"The winner's chance by our rating before the match."}}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"example":{"request":"GET https://api.badmintonapi.com/v1/analysis/upsets"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"by","in":"query","required":false,"schema":{"type":"string","enum":["price","rating"],"default":"price"}},{"name":"discipline","in":"query","required":false,"description":"MS, WS, MD, WD or XD.","schema":{"type":"string","enum":["MS","WS","MD","WD","XD"]}},{"name":"from","in":"query","required":false,"schema":{"type":"integer","minimum":1899}},{"name":"to","in":"query","required":false,"schema":{"type":"integer","minimum":1899}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}]}},"/v1/analysis/seeds":{"get":{"operationId":"seeds","summary":"How seeds perform","description":"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. Plan: Archive. MCP tool: seed_performance.","tags":["Odds and analysis"],"x-plan":"archive","externalDocs":{"url":"https://badmintonapi.com/documentation/seeds"},"responses":{"200":{"description":"The answer: data, and meta with counts, pages and notes.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","properties":{"by_seed":{"description":"For each seed: draws, win rate, and how often it reached the semi-final, the final and the title."},"by_round":{"description":"Seeded against unseeded, round by round: matches and the seed's win rate."}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"example":{"request":"GET https://api.badmintonapi.com/v1/analysis/seeds"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"discipline","in":"query","required":false,"description":"MS, WS, MD, WD or XD.","schema":{"type":"string","enum":["MS","WS","MD","WD","XD"]}},{"name":"from","in":"query","required":false,"schema":{"type":"integer","minimum":1899}},{"name":"to","in":"query","required":false,"schema":{"type":"integer","minimum":1899}}]}},"/v1/analysis/deciders":{"get":{"operationId":"deciders","summary":"Deciding games","description":"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. Plan: Archive. MCP tool: deciding_games.","tags":["Odds and analysis"],"x-plan":"archive","externalDocs":{"url":"https://badmintonapi.com/documentation/deciders"},"responses":{"200":{"description":"The answer: data, and meta with counts, pages and notes.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","properties":{"decade":{"description":"The decade, like 1990."},"matches":{"description":"Matches played, or the matches themselves."},"three_games":{"description":"Share of matches that went to a third game."},"won_after_losing_first_game":{"description":"Share of matches won by the side that lost the first game."},"points_per_game":{"description":"Average points played in a game."},"extended_games":{"description":"Games where the loser reached 20 (21-point scoring, 2006 on): played, won, rate."}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"example":{"request":"GET https://api.badmintonapi.com/v1/analysis/deciders"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"by","in":"query","required":false,"schema":{"type":"string","enum":["decade","year"],"default":"decade"}},{"name":"discipline","in":"query","required":false,"description":"MS, WS, MD, WD or XD.","schema":{"type":"string","enum":["MS","WS","MD","WD","XD"]}},{"name":"from","in":"query","required":false,"schema":{"type":"integer","minimum":1899}},{"name":"to","in":"query","required":false,"schema":{"type":"integer","minimum":1899}}]}},"/v1/analysis/records":{"get":{"operationId":"records","summary":"Records","description":"Records: most titles, most finals, longest winning runs, widest winning margins and most points in a match. Plan: Archive. MCP tool: records.","tags":["Odds and analysis"],"x-plan":"archive","externalDocs":{"url":"https://badmintonapi.com/documentation/records"},"responses":{"200":{"description":"The answer: data, and meta with counts, pages and notes.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"player":{"description":"The player: id, name and country."},"count":{"description":"The record: titles, finals, wins in a row, a margin or points."},"first_year":{"description":"The first year held."},"last_year":{"description":"The latest year held."},"match":{"description":"The mt_ id of the draw match."}}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"example":{"request":"GET https://api.badmintonapi.com/v1/analysis/records?type=most_titles"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"type","in":"query","required":true,"schema":{"type":"string","enum":["most_titles","most_finals","longest_win_streak","widest_margin","most_points"]}},{"name":"discipline","in":"query","required":false,"description":"MS, WS, MD, WD or XD.","schema":{"type":"string","enum":["MS","WS","MD","WD","XD"]}},{"name":"from","in":"query","required":false,"schema":{"type":"integer","minimum":1899}},{"name":"to","in":"query","required":false,"schema":{"type":"integer","minimum":1899}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}]}},"/v1/analysis/market":{"get":{"operationId":"market","summary":"Market accuracy","description":"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. Plan: Odds. MCP tool: market_accuracy.","tags":["Odds and analysis"],"x-plan":"odds","externalDocs":{"url":"https://badmintonapi.com/documentation/market"},"responses":{"200":{"description":"The answer: data, and meta with counts, pages and notes.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","properties":{"favourite_by_price":{"description":"For each price band: matches, the market's chance, how often favourites won, the return at the close."},"favourite_by_round":{"description":"The closing favourite by round (R64 to F): matches, the market's expected win rate and the actual one."},"favourite_by_seeding":{"description":"The closing favourite by seeding, favourite first (seeded_v_unseeded and so on): matches, expected and actual win rate."},"bookmakers":{"description":"Each bookmaker: its prices, or its average margin."}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"example":{"request":"GET https://api.badmintonapi.com/v1/analysis/market"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"discipline","in":"query","required":false,"description":"MS, WS, MD, WD or XD.","schema":{"type":"string","enum":["MS","WS","MD","WD","XD"]}},{"name":"from","in":"query","required":false,"schema":{"type":"integer","minimum":1899}},{"name":"to","in":"query","required":false,"schema":{"type":"integer","minimum":1899}}]}},"/v1/odds/{id}":{"get":{"operationId":"odds","summary":"Match odds","description":"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. Plan: Odds. MCP tool: match_odds.","tags":["Odds and analysis"],"x-plan":"odds","externalDocs":{"url":"https://badmintonapi.com/documentation/odds"},"responses":{"200":{"description":"The answer: data, and meta with counts, pages and notes.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","properties":{"match":{"description":"The mt_ id of the draw match."},"event":{"description":"The ev_ id of the same match in the results feed, when linked."},"summary":{"description":"The market across bookmakers."},"bookmakers":{"description":"Each bookmaker: its prices, or its average margin."},"lines":{"description":"Handicap and total lines: kind (handicap or total), unit (games or points), the line (a handicap's is side 1's), each bookmaker's opening and closing prices, and the average close. Handicap prices are side 1 then side 2; total prices are over then under."}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"example":{"request":"GET https://api.badmintonapi.com/v1/odds/mt_3bt85wzp"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Which one, by its id.","schema":{"type":"string","description":"mt_ or ev_ id"}}]}},"/v1/backtest":{"get":{"operationId":"backtest","summary":"Backtest a strategy","description":"Run a simple strategy over every settled match with closing prices: strike rate, return and how far it is from chance. Plan: Odds. MCP tool: backtest_strategy.","tags":["Odds and analysis"],"x-plan":"odds","externalDocs":{"url":"https://badmintonapi.com/documentation/backtest"},"responses":{"200":{"description":"The answer: data, and meta with counts, pages and notes.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","properties":{"strategy":{"description":"The strategy tested."},"filters":{"description":"The filters applied."},"bets":{"description":"Bets the strategy placed."},"won":{"description":"Bets or matches won."},"strike_rate":{"description":"Share of bets won."},"market_chance":{"description":"The average chance the closing market gave the side backed."},"roi_average":{"description":"Return a bet at the average closing price."},"roi_best":{"description":"Return a bet at the best closing price."},"z":{"description":"How far the return is from chance, in standard errors; under 2 is noise."},"by_year":{"description":"The same figures year by year."}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"example":{"request":"GET https://api.badmintonapi.com/v1/backtest?strategy=favourite"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"strategy","in":"query","required":true,"description":"Favourite, outsider, seeded, unseeded, steam (the side the market moved to) or drift.","schema":{"type":"string","enum":["favourite","outsider","seeded","unseeded","steam","drift"]}},{"name":"discipline","in":"query","required":false,"description":"MS, WS, MD, WD or XD.","schema":{"type":"string","enum":["MS","WS","MD","WD","XD"]}},{"name":"round","in":"query","required":false,"description":"R128, R64, R32, R16, QF, SF, 3P or F.","schema":{"type":"string","enum":["R128","R64","R32","R16","QF","SF","3P","F"]}},{"name":"from","in":"query","required":false,"schema":{"type":"integer","minimum":1899}},{"name":"to","in":"query","required":false,"schema":{"type":"integer","minimum":1899}},{"name":"min_price","in":"query","required":false,"description":"Lowest average closing price backed.","schema":{"type":"number"}},{"name":"max_price","in":"query","required":false,"description":"Highest average closing price backed.","schema":{"type":"number"}}]}},"/v1/live":{"get":{"operationId":"live","summary":"Live scores","description":"Matches under way now, with the score so far. Plan: Live. MCP tool: live_scores.","tags":["Live"],"x-plan":"live","externalDocs":{"url":"https://badmintonapi.com/documentation/live"},"responses":{"200":{"description":"The answer: data, and meta with counts, pages and notes.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"description":"The id: pl_, tr_, mt_, ev_ or vn_, never changing."},"tournament":{"description":"The tournament: id, name and year."},"discipline":{"description":"MS, WS, MD, WD or XD."},"team_event":{"description":"True for a tie in a team event."},"start":{"description":"The first day or start time."},"status":{"description":"scheduled, live, finished; or finished, in_progress, upcoming."},"side1":{"description":"The first side: players and seed."},"side2":{"description":"The second side: players and seed."},"sets":{"description":"Games won by each side."},"games":{"description":"Game scores, like [[21,17],[19,21],[21,15]]; side 1 first unless stated."},"winner":{"description":"The winning side: 1 or 2, or its players."},"match":{"description":"The mt_ id of the draw match."},"odds":{"description":"Prices: bookmakers counted, opening, closing and best prices, the market's chance and margin. Odds plan."},"duration_min":{"description":"How long a finished match lasted, in minutes, from its start to its final point; null until it has finished, and for older matches whose record keeps no end time."}}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"example":{"request":"GET https://api.badmintonapi.com/v1/live"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/live/stream":{"get":{"operationId":"liveStream","summary":"Live stream","description":"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. Plan: Live.","tags":["Live"],"x-plan":"live","externalDocs":{"url":"https://badmintonapi.com/documentation/live-stream"},"responses":{"200":{"description":"Server-Sent Events. hello: Event, on connect: plan, discipline (the filter, or null), closes_at (when the server will end this connection) and check_seconds. snapshot: Event, on connect: data, every match in play as /v1/live gives them, and meta with count and at. match: Event: one match, as /v1/live gives it, whenever its score, status or prices change; a match that finishes is sent once more with status finished and its final score. seen: Event, every 15 seconds when nothing has changed: live (matches in play) and at. It also keeps the connection open through proxies. bye: Event, before the server ends the connection: reconnect. EventSource reconnects by itself; a new connection is a new call and starts with a fresh snapshot.","content":{"text/event-stream":{"schema":{"type":"string"},"example":"event: match\ndata: {\"id\": \"ev_...\", \"status\": \"live\", \"games\": [[21, 17], [8, 6]]}\n\n"}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-stream":true,"parameters":[{"name":"discipline","in":"query","required":false,"description":"MS, WS, MD, WD or XD.","schema":{"type":"string","enum":["MS","WS","MD","WD","XD"]}}]}},"/v1/events/{id}/points":{"get":{"operationId":"eventPoints","summary":"Point by point","description":"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. Plan: Archive. MCP tool: match_points.","tags":["Live"],"x-plan":"archive","externalDocs":{"url":"https://badmintonapi.com/documentation/event-points"},"responses":{"200":{"description":"The answer: data, and meta with counts, pages and notes.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"event":{"description":"The match, as /v1/events/{id} gives it."},"complete":{"description":"True once the match has finished and its rallies were read after it: they are final."},"read":{"description":"When the rallies were last read, UTC."},"games":{"description":"Each game: game, score, rallies, and points, every rally in order with n, score after it (side 1 first), won (1 or 2) and server (1 or 2, null when not given)."},"totals":{"description":"For side1 and side2: points_won, served, won_on_serve, won_receiving and longest_run (the most rallies won in a row, across games)."}}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"example":{"request":"GET https://api.badmintonapi.com/v1/events/ev_trk0gykq/points"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Which one, by its id.","schema":{"type":"string","description":"ev_ id"}}]}},"/v1/usage":{"get":{"operationId":"usage","summary":"Your usage","description":"Your key: plan, calls today and this month, limits and when they reset. Free to call. Plan: Free key. Never counted against your calls.","tags":["Your key"],"x-plan":"free","externalDocs":{"url":"https://badmintonapi.com/documentation/usage"},"responses":{"200":{"description":"The answer: data, and meta with counts, pages and notes.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","properties":{"key":{"description":"Your key's prefix."},"plan":{"description":"Your plan."},"calls":{"description":"Calls today and this month."},"limits":{"description":"Calls a minute and a day on your plan."},"remaining":{"description":"Calls left this minute and today."},"resets":{"description":"When the minute and the day reset."},"data":{"description":"What your plan covers: every year, or yesterday and today."}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"example":{"request":"GET https://api.badmintonapi.com/v1/usage"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Authorization: Bearer <your key>. A free key comes with every account."},"apiKey":{"type":"apiKey","in":"header","name":"X-API-Key"}},"schemas":{"Meta":{"type":"object","description":"Counts, pages and notes about the answer. Lists add count, page, per_page, total, total_pages, next_page, prev_page and next_cursor.","additionalProperties":true},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["bad_request","unauthorized","upgrade_required","not_found","unknown_parameter","rate_limited","quota_exceeded","server_error"]},"message":{"type":"string"},"docs":{"type":"string","format":"uri"}}}}}},"responses":{"Error":{"description":"One error shape for every failure; the code says what to do.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"externalDocs":{"description":"Documentation","url":"https://badmintonapi.com/documentation"}}