Ids and search

Every thing the API returns has an id that says what it is and never changes once given, so it is safe to store in your own database and use as a join key. Names change (a player marries, a tournament takes a sponsor's name) and repeat (two players called Lee Yong-dae would be hard to tell apart), but ids do not.

Two kinds of match

A mt_ match is a match in a tournament's draw, from the first round to the final, held back to 1899. An ev_ event is a result or fixture from the live and results side, with start times, prices and, from 2022, point by point. Where both describe the same match they are linked, so a draw match shows its prices and a result shows its round.

Finding an id with search

/v1/search works on every plan. Accents and capitals do not matter, so marin finds Carolina Marín. Search for a pair with a slash: lee chong wei / lin dan finds both players. Add a year to a tournament's name to get that edition: all england 2023. Narrow it to one kind with kind.

curl -s "https://api.badmintonapi.com/v1/search?q=all%20england%202023" \
  -H "Authorization: Bearer $BADMINTON_API_KEY"

curl -s "https://api.badmintonapi.com/v1/search?q=axelsen&kind=player" \
  -H "Authorization: Bearer $BADMINTON_API_KEY"

{
  "data": [{
    "kind": "tournament",
    "id": "tr_XXXXXXXX",
    "name": "2023 All England Open"
  }],
  "meta": { "count": 1, "query": "all england 2023" }
}

From a name to everything else

hit = get("/search", q="tai tzu ying", kind="player")["data"][0]
pid = hit["id"]

profile  = get(f"/players/{pid}")["data"]
rivals   = get(f"/players/{pid}/opponents")["data"]
titles   = get(f"/players/{pid}/titles")["data"]
print(profile["name"], len(titles), "titles")

Store the id, not the name, and you will never need to search for the same thing twice. Countries are the exception to the prefix rule: they use the three-letter IOC code (DEN, CHN, INA), which is what the sport itself uses on scoreboards and in draws.

Ids in addresses

Ids go straight into the path where an endpoint is about one thing: /v1/players/pl_XXXXXXXX, /v1/tournaments/tr_XXXXXXXX/draw, /v1/events/ev_XXXXXXXX. Where an endpoint takes an id as a filter, it is a parameter instead: /v1/matches?player=pl_XXXXXXXX. An id of the wrong kind in the wrong place (a tr_ id where a player belongs) answers 404 not_found, never another thing's data.