Dates and times

Every time in the API is UTC, so a match in Jakarta and one in Copenhagen sort into the right order without any time zone arithmetic. There are three forms, and each field uses one of them consistently.

Asking by date

Parameters that take a day want YYYY-MM-DD; anything else answers 400 bad_request naming the parameter. A day means the UTC day, from 00:00 to 23:59:59 UTC. Years are four digits.

# results on one UTC day
curl -s "https://api.badmintonapi.com/v1/results?date=2026-09-28" -H "Authorization: Bearer $BADMINTON_API_KEY"

# the world ranking as it stood on a day
curl -s "https://api.badmintonapi.com/v1/rankings?date=2019-03-11&discipline=MS" -H "Authorization: Bearer $BADMINTON_API_KEY"

from datetime import datetime
from zoneinfo import ZoneInfo

start = "2026-10-11T06:30:00Z"
utc = datetime.fromisoformat(start.replace("Z", "+00:00"))
print(utc.astimezone(ZoneInfo("Asia/Bangkok")))
# 2026-10-11 13:30:00+07:00

const start = new Date("2026-10-11T06:30:00Z");
console.log(start.toLocaleString(undefined, {
  dateStyle: "medium", timeStyle: "short",
}));  // in the viewer's own time zone

Tournament dates

A tournament's start and end are its first and last day where the record gives them. The oldest editions carry the year alone, and their days are null rather than a guess, so do not fill them with 1 January. A rating or ranking "as of" a tournament uses its last day, or 31 December of its year when the days are unknown.

Ranking dates

Weekly world ranking lists are dated the Monday they count from. Ask for any day and you get the newest list on or before it. In 2020 the ranking was frozen from week 12 until the tour resumed in January 2021, so lists from that time repeat the frozen order: that is how they were published, not a gap in the data.

Times that move

A fixture's start time is the time scheduled when it was read, and schedules slip: an earlier match runs long, or a session is moved. Read a fixture again shortly before it starts rather than relying on a time read days earlier. Once a match is in play its status becomes live, and once it ends, finished, so check the status rather than comparing the start time with the clock. On the Live plan the stream and webhooks tell you the moment a match starts, which is more reliable than any schedule.