---
name: badmintonapi
description: World badminton data from badmintonapi.com as a JSON API and an MCP server: results, fixtures, draws back to 1899, players, head to head, world rankings, venues, closing prices with handicap and total lines, career-high rankings, ratings and live scores. Use when a question needs real badminton results, players, rankings or odds.
---

# Badminton API

World badminton as one clean JSON API and an MCP server, run by DeveloperData.net.
Results and fixtures, every tournament draw back to 1899, players, head to head, world rankings, venues and host cities, bookmaker prices, an own player rating with win chances, and live scores.

## When to use it

- Use it for facts about badminton matches, players, tournaments, rankings and prices: who won, scores, draws, records, form, head to head.
- Do not use it for news, injuries, interviews or anything that is not a result, a draw, a ranking or a price.
- Prices, ratings and win chances are information, not betting or financial advice.

## Getting access

- Sign in with Google at https://badmintonapi.com/login. A free key is made at once, with no card.
- Keys are managed at https://badmintonapi.com/account/keys. A key starts with `bda_live_`.
- Send the key in a header on every call: `X-API-Key: <your key>` (or `Authorization: Bearer <your key>`). Never put it in the address.
- Base address: `https://api.badmintonapi.com/v1`. Every time is UTC.

## The calls for common questions

Every answer is `{"data": ..., "meta": {...}}`. Lists page with `page` and `per_page` (up to 200), and `meta.next_cursor` gives the next page.

Yesterday's results (free):

```
curl -H "X-API-Key: $BADMINTON_API_KEY" https://api.badmintonapi.com/v1/results/yesterday
```

Matches finished on a day (free for yesterday and today, Archive for every day held):

```
curl -H "X-API-Key: $BADMINTON_API_KEY" "https://api.badmintonapi.com/v1/results?date=2026-09-28&discipline=MS"
```

What is coming up, and what is under way (free):

```
curl -H "X-API-Key: $BADMINTON_API_KEY" https://api.badmintonapi.com/v1/fixtures
```

Find a player, pair, tournament, country, venue or city by name (free):

```
curl -H "X-API-Key: $BADMINTON_API_KEY" "https://api.badmintonapi.com/v1/search?q=axelsen"
```

The ids in answers carry a prefix (`pl_` a player, `mt_` a draw match, `ev_` a results match, and so on). Pass them on as they are.

A player (with their best world ranking in `career_high`), their matches, titles and head to head (Archive):

```
curl -H "X-API-Key: $BADMINTON_API_KEY" https://api.badmintonapi.com/v1/players/{id}
curl -H "X-API-Key: $BADMINTON_API_KEY" https://api.badmintonapi.com/v1/players/{id}/matches
curl -H "X-API-Key: $BADMINTON_API_KEY" https://api.badmintonapi.com/v1/players/{id}/titles
curl -H "X-API-Key: $BADMINTON_API_KEY" "https://api.badmintonapi.com/v1/h2h?player1={id}&player2={id}"
```

A tournament edition (with each event's medallists in `podium`), its whole draw, and a series' roll of honour (Archive):

```
curl -H "X-API-Key: $BADMINTON_API_KEY" https://api.badmintonapi.com/v1/tournaments/{id}
curl -H "X-API-Key: $BADMINTON_API_KEY" https://api.badmintonapi.com/v1/tournaments/{id}/draw
curl -H "X-API-Key: $BADMINTON_API_KEY" https://api.badmintonapi.com/v1/series/all-england/champions
```

The world ranking for a discipline, now or on a date (Archive):

```
curl -H "X-API-Key: $BADMINTON_API_KEY" "https://api.badmintonapi.com/v1/rankings?discipline=WS"
```

Opening and closing prices for a match (the match winner, plus handicap and total lines in games and points in `lines`), and a win chance from our rating (Odds):

```
curl -H "X-API-Key: $BADMINTON_API_KEY" https://api.badmintonapi.com/v1/odds/{id}
curl -H "X-API-Key: $BADMINTON_API_KEY" "https://api.badmintonapi.com/v1/predict?player1={id}&player2={id}"
```

Matches under way now, with the score so far (Live):

```
curl -H "X-API-Key: $BADMINTON_API_KEY" https://api.badmintonapi.com/v1/live
```

Check your own key, plan and what is left today (free, not counted):

```
curl -H "X-API-Key: $BADMINTON_API_KEY" https://api.badmintonapi.com/v1/usage
```

Every endpoint, parameter and field is in the manual: https://badmintonapi.com/documentation/manual.md

## MCP server

`https://api.badmintonapi.com/mcp` (JSON-RPC 2.0 over HTTP POST), with the same key in `X-API-Key` or `Authorization: Bearer`. Tools include `yesterdays_results`, `results_on_date`, `upcoming_matches`, `search`, `find_player`, `player_matches`, `player_titles`, `head_to_head`, `tournament_draw`, `roll_of_honour`, `world_rankings`, `player_ratings`, `win_chance`, `match_odds`, `backtest_strategy`, `live_scores` and `match_points`. `tools/list` gives the full set with their inputs.

## Limits

| Plan | Calls a minute, per key | Calls a day, per key | What it adds |
|---|---|---|---|
| Free key | 10 | 50 | Yesterday, today, the fixtures ahead, search |
| Archive | 60 | 5,000 | Every draw back to 1899, players, head to head, rankings, analysis |
| Odds | 120 | 20,000 | Opening and closing prices, win chances, backtests |
| Live | 300 | 100,000 | Scores as they happen |

- Every answer carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-Quota-Remaining`.
- The daily allowance resets at 00:00 UTC.
- A field a lower plan does not include comes back as `null`, and `meta.note` says which plan has it.

## Errors

Errors are `{"error": {"code": "...", "message": "...", "docs": "..."}}`, with `plan` added when a higher plan is needed.

| HTTP | code | What to do |
|---|---|---|
| 400 | `bad_request` | Fix the parameter the message names. |
| 401 | `unauthorized` | Send a valid, active key in `X-API-Key`. |
| 403 | `upgrade_required` | The endpoint needs the plan named in `plan`. |
| 404 | `not_found` | The id or address does not exist. |
| 422 | `unknown_parameter` | Drop the parameter the message names. |
| 429 | `rate_limited` / `quota_exceeded` | Wait for `Retry-After` seconds. |
| 500 | `server_error` | Try again shortly; https://badmintonapi.com/status shows the service's state. |

## A typical workflow

1. Call `/v1/usage` once to learn the plan and what is left today.
2. Turn names into ids with `/v1/search?q=...`.
3. Answer with the narrowest call: a player's `matches`, `titles` or `form`, a tournament's `draw`, `/v1/h2h`, `/v1/rankings`.
4. Page with `meta.next_cursor` only when the question needs more than the first page.
5. On a 429, wait for `Retry-After`; on a 403, say which plan the data needs rather than retrying.
6. Say that dates and times are UTC, and that prices and win chances are not betting advice.