Football Fixtures by Date in Python: YYYYMMDD Is Not the Viewer's Thursday
The request field is eight digits: date=20261008. It looks like Thursday, 8 October 2026 on a wall calendar. It is not the viewer's Thursday. get-matches-events-by-date groups kickoffs around that token. The same JSON can hold a UTC Wednesday night that is already Thursday in Shanghai, and a 0–0 that has not started. Neither is a reason to file the row under “that Thursday’s finished draw.”
Sign in, copy an authorized key from the dashboard, and read it from OPENDATA_API_KEY on a server. YOUR_API_KEY in snippets is a placeholder. The key rides in the query string, so those URLs do not belong in tickets, screenshots, or browser JavaScript. Opening this page or copying an example does not send a request.
The Football Data API does not declare a timezone parameter on this operation. Send YYYYMMDD, not YYYY-MM-DD. A format error usually fails at the gateway. A timezone error fails in your grouping, with HTTP still green.
The request date is not the viewer's Thursday
A demonstrated 20261008 payload included UTC kickoffs spanning 7–8 October. That does not prove the source calendar is UTC, a padded UTC day, or the viewer's zone. It only proves a date request is a discovery window. There is no documented selector that says “Asia/Shanghai Thursday.”
Three misses look alike until you split them:
- Transport or auth never ran: HTTP 4xx/5xx, missing key, quota, or network. Inspect credentials and credits only on that layer.
- The platform rejected the call: the gateway envelope is
{code, message, data}. Gatewaycode=200is business success. HTTP 200 alone is not. - The football payload ran and still has nothing you can render:
data.statusis not"success",response.matchesis missing or not a list, or the list is empty. An empty successful list is not “no football happened worldwide.” Coverage is competition-specific and unstated for a given day.
get-search-all with search=Real Madrid is a typed-suggestion lookup, not a calendar. Use it when you need a team or event ID. A successful search can return suggestions=[]. That is a miss, not an HTTP failure, and it does not mean the dated fixture call failed.
Do not invent a timezone query argument. Do not group on the first ten characters of status.utcTime. Convert each kickoff, then decide whether it belongs on the viewer's day.
Read match state before the score
Home and away objects carry score. Scheduled rows often sit at 0–0. That is a placeholder, not a result. Classify with flags, not arithmetic on the scores.
Read cancelled, started, and finished from status, and from the row if they also appear there. Cancellation wins. started=false and finished=false is a scheduled snapshot. started=true and finished=false is started and not finished — not a promise of uninterrupted live play, and not a final. finished=true is the only snapshot you should treat as a completed scoreline. Missing or conflicting flags stay unknown. Finished examples have also included status.scoreStr and status.reason; do not assume every row has them.
Keep id and leagueId as keys. Deduplicate on event id. Home and away each expose id, name, longName, and score; a missing score is not a zero you may fill in. statusId, tournamentStage, and millisecond timeTS are extra context — confirm nesting and units before you use timeTS as a clock.
If you later pass a fixture id as eventid into get-match-event-detail-by-event-id, retain the fixture score. The demonstrated detail record did not include a final score.
Convert UTC with zoneinfo
Python 3.9 or later, with requests. zoneinfo needs IANA data; install tzdata if the environment lacks it. The script caches validated successes for five minutes as an application example, not a promised update interval. Credentials stay out of cache keys. It fails on unexpected structure instead of printing “no fixtures.” Adjacent source dates fill a local Thursday for Asia/Shanghai; last-fetched row wins on duplicate IDs.
import os
from datetime import date, datetime
from time import monotonic
from zoneinfo import ZoneInfo
import requests
BASE = "https://api.opendata-api.com/api/project/football"
KEY = os.environ["OPENDATA_API_KEY"]
CACHE_TTL = 300
cache = {}
def call(operation, **params):
cache_key = (operation, tuple(sorted(params.items())))
cached = cache.get(cache_key)
if cached and monotonic() - cached[0] < CACHE_TTL:
return cached[1]
try:
result = requests.get(
f"{BASE}/{operation}",
params={**params, "key": KEY},
timeout=30,
)
except requests.RequestException:
raise RuntimeError("Football request failed") from None
if not 200 <= result.status_code < 300:
raise RuntimeError(f"HTTP failure: {result.status_code}")
envelope = result.json()
if envelope.get("code") != 200:
raise RuntimeError("Gateway business failure; inspect redacted status")
payload = envelope.get("data")
if not isinstance(payload, dict) or payload.get("status") != "success":
raise RuntimeError("Football payload is not successful")
response = payload.get("response")
if not isinstance(response, dict):
raise RuntimeError("Unexpected football response structure")
cache[cache_key] = (monotonic(), response)
return response
def match_state(match):
status = match.get("status") or {}
flags = {
name: status.get(name, match.get(name))
for name in ("cancelled", "started", "finished")
}
if flags["cancelled"] is True:
return "cancelled"
if flags["finished"] is True:
return "finished"
if flags["finished"] is False:
if flags["started"] is True:
return "started, not finished"
if flags["started"] is False:
return "scheduled"
return "unknown"
local_day = date(2026, 10, 8)
viewer_zone = ZoneInfo("Asia/Shanghai")
source_dates = ["20261007", "20261008", "20261009"]
by_event_id = {}
for source_date in source_dates:
rows = call("get-matches-events-by-date", date=source_date).get("matches")
if not isinstance(rows, list):
raise RuntimeError("Expected response.matches to be an array")
for match in rows:
by_event_id[str(match["id"])] = match
for event_id, match in by_event_id.items():
try:
utc_text = match["status"]["utcTime"]
kickoff = datetime.fromisoformat(utc_text.replace("Z", "+00:00"))
if kickoff.tzinfo is None:
raise ValueError("Kickoff lacks a timezone")
except (KeyError, TypeError, ValueError, AttributeError):
# Quarantine unusable timestamps; do not drop them into the local day.
continue
local_kickoff = kickoff.astimezone(viewer_zone)
if local_kickoff.date() != local_day:
continue
print({
"event_id": event_id,
"league_id": match.get("leagueId"),
"home_id": match.get("home", {}).get("id"),
"away_id": match.get("away", {}).get("id"),
"kickoff_local": local_kickoff.isoformat(),
"state": match_state(match),
"home_score": match.get("home", {}).get("score"),
"away_score": match.get("away", {}).get("score"),
})
Run it on purpose. Store a retrieval timestamp with any snapshot you persist. Share identical reads across users. Slow the refresh after finished=true, and keep a path for later corrections. Use bounded backoff on transport failures; do not retry an empty successful list as if the network blinked. These are GET snapshots, not a live push subscription and not a latency guarantee.
What a date window will miss
A three-day pad around 20261008 is a Shanghai-oriented guess, not a completeness proof. Late kickoffs in Pacific/Auckland or early ones in America/Los_Angeles can sit outside that pad. Named zones such as Europe/London beat a hardcoded +8 when daylight saving applies. Adjacent reads cost extra credits; they still do not mean every competition, every stadium, or every postponed kickoff landed in the merge.
Optional follow-ups are outside the window. Pass a real fixture id as eventid only for events you will show. leagueId can feed get-standing-all-by-league-id; the overall Premier League sample used leagueid=47 and returned played, wins, draws, losses, scoresStr, goalConDiff, pts, and idx. Preserve returned order. Do not invent tie-breaks or treat a home/away split table as overall rank. A team suggestion can feed get-team-detail-by-team-id; the demonstrated teamid=8633 resolved to Real Madrid. Lineups, odds, and period statistics are event-specific. Catalogue presence is not coverage.
This call will not accept a timezone query parameter, stream live scores, or tell you that an empty day means football stopped. Compare usable coverage, quota, and data-use rights on pricing before treating a local calendar as complete. Read the current parameter contract on the fixtures-by-date reference.