Documentation · Badminton API

Start here

Three steps from nothing to your first answer. The Quick start walks through them with code in four languages.

1Get a free key
Sign in with Google and your key is made at once: 50 calls a day, no card, no expiry.
Get a free key
2Send it as a header
Authorization: Bearer bda_live_… on every call to https://api.badmintonapi.com/v1.
Authentication
3Read data, check meta
Every answer has the same two parts: what you asked for, and the counts, pages and notes about it.
Quick start

Every endpoint page has Try it: paste your key once and it is kept in this browser, the parameters are a form, and Run calls the API and shows the answer.

What you can ask for

The questions people come with, each answered by one call. The examples use real ids: open one and press Run.

Yesterday's results, every match GET /v1/results/yesterday Yesterday's resultsFree key What is on next, with start times GET /v1/fixtures FixturesFree key A player's career at a glance GET /v1/players/pl_9k1rzjad Player profileArchive Every match a player has played GET /v1/players/pl_9k1rzjad/matches Player matchesArchive A tournament's whole draw GET /v1/tournaments/tr_0574err6/draw?discipline=MS Tournament drawArchive Two players against each other GET /v1/h2h?player1=pl_9k1rzjad&player2=pl_hmfabfyf Head to headArchive The world ranking on any date GET /v1/rankings?discipline=MS World rankingsArchive Opening and closing prices for a match GET /v1/odds/mt_3bt85wzp Match oddsOdds Backtest backing the favourite GET /v1/backtest?strategy=favourite Backtest a strategyOdds Scores while play is on GET /v1/live Live scoresLive

What is in it

Counted from the archive itself, every hour. The full list of tournaments and how far back each goes is on Coverage.

129,194: draw matches, first round to final
1,141: tournament editions since 1899
84: series: majors, tours, continental, Games, juniors, para
20,984: players with careers, partners and rivals
1,731: team-event ties, Thomas, Uber and Sudirman Cups
11,207: matches with closing prices, from 2012
9,783: matches with handicap and total lines
422: venues, with their host cities

Every endpoint

45 endpoints in 9 groups. Each has its own page with every parameter, every field and Try it. The dot is the plan it comes with.

Search and countries

One search across every name, and every nation that plays.

Results and calendar

Yesterday, today, the fixtures ahead and the season's calendar.

Tournaments and draws

Every edition and every draw, first round to final, back to the first All England in 1899.

Players

Careers, partners, rivals, titles, form, game statistics and ranking history.

Rankings and ratings

The world ranking as published, and our own rating and win chance.

Venues and cities

The arena and city of every edition held.

Odds and analysis

Opening and closing prices, backtests, upsets, seeds, deciding games and records.

Live

Scores while the shuttle is in the air.

Your key

What your key can do, and what it has used.

Your usage/v1/usage

Free keyArchiveOddsLive

How the API works

The rules every endpoint follows. Read them once and every page of these docs reads the same way.

Quick startA key, one call and your first answer in five minutes. AuthenticationYour key in a header, never in the address, and how keys are kept. ResponsesAlways JSON: data and meta when it works, one error shape when it does not. Rate limitsCalls a minute and a day on each plan, the headers on every answer, and what a 429 means. ErrorsEvery status and error code, what it means and what to do about it. Pages of resultsLong lists by page number or by cursor, up to 200 a page. Ids and searchIds that never change, and search to find them by name. Plans and fieldsFields above your plan come back as null with a note, so your code never changes. Dates and timesEvery time in UTC, in ISO 8601, and how tournament dates are given. MCP for AI assistantsThe same data as 37 tools for any MCP client, on the same key. MCP tools Webhooks Use with Claude and agentsOne SKILL.md that teaches an AI agent the whole API.

Plans at a glance

Every plan answers the same shape, and each has every endpoint of the plans before it. Change plan at any time and the same key sees more at once. Compare plans.

Plan	Price	Calls a minute	Calls a day	Endpoints
Free key	Free	10	50	9
Archive	$19 a month	60	5,000	38
Odds	$49 a month	120	20,000	43
Live	$149 a month	300	100,000	45

For AI assistants and agents

Ask in plain words and let an assistant make the calls, on the same key, plan and limits.

MCP server37 read-only tools at api.badmintonapi.com/mcp, for Claude and any MCP client. Agent skillOne SKILL.md that teaches an agent the whole API, at /skill.md. The whole manualEvery guide and endpoint as one Markdown file, /llms.txt, and the API as OpenAPI 3.1 at /openapi.json.

Help

Answers to the common questions first, and a person on every ticket.

Support and FAQCommon questions answered, and a ticket to us when you need one. StatusThe website, the API and the MCP server, with uptime and incidents. ChangelogEvery change to the API, newest first.

Build with world badminton data.