Quick start

What just happened

The call above asked /v1/search for a name and got back one player with an id that starts pl_. That id is the key to everything else about the player: their matches, partners, rivals, titles, form and ranking history are all one call away, and the id never changes, so you can keep it in your own tables.

Every answer from the API has the same two parts. data is what you asked for: one object for a single thing, a list for many. meta says how many there were, which page you are on, and anything you should know about the answer, such as a field your plan does not include. Read data, glance at meta, and you have read every endpoint.

Your second and third calls

Once you have an id, ask about it. These three calls take a player from a name to their last five results and the next match they are due to play.

export BADMINTON_API_KEY=bda_live_...

# 1. find the player
curl -s "https://api.badmintonapi.com/v1/search?q=an%20se-young" -H "Authorization: Bearer $BADMINTON_API_KEY"

# 2. their recent results (use the id from step 1)
curl -s "https://api.badmintonapi.com/v1/players/pl_XXXXXXXX/form" -H "Authorization: Bearer $BADMINTON_API_KEY"

# 3. yesterday's results across every event
curl -s "https://api.badmintonapi.com/v1/results/yesterday" -H "Authorization: Bearer $BADMINTON_API_KEY"

import os, requests

BASE = "https://api.badmintonapi.com/v1"
AUTH = {"Authorization": f"Bearer {os.environ['BADMINTON_API_KEY']}"}

def get(path, **params):
    r = requests.get(BASE + path, params=params, headers=AUTH, timeout=20)
    body = r.json()
    if not r.ok:
        raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
    return body

player = get("/search", q="an se-young")["data"][0]
print(player["name"], player["id"])
for m in get("/results/yesterday")["data"][:5]:
    print(m["id"], m.get("games"))

Keep the key out of your code

Put the key in an environment variable or your platform's secret store, never in the source file, a public repository or a web page that anyone can open. The examples on these pages all read BADMINTON_API_KEY from the environment for that reason. If a key does leak, replace it from your account in one click: the old one stops working at once and nothing else changes.

Where to go next

Authentication explains the two headers and how keys are kept. Responses walks through the answer's shape. Rate limits shows how many calls your plan allows and how to stay inside them. Every endpoint has its own page with a Try it panel, so you can run real calls from the browser before writing any code. The free key reads yesterday, today and the fixtures ahead; the archive back to 1899, odds and live scores come with the paid plans, on the same key.