用 Python 按日期拉足球赛程:YYYYMMDD 不是观众的星期四
查询里真正要命的字段只有一个:date=20261008。八位数字看起来就是墙上日历的星期四。它不是观众手机上的星期四。get-matches-events-by-date 按这串日期把开球收进一个窗口;同一份 JSON 里可以有 UTC 周三夜里、上海已是周四的比赛,也可以有比分仍写着 0–0、根本还没开球的场次。前者不是「请求日」,后者不是完赛平局。做球迷日历时,最容易把这两个误读叠在一起:日期用错一天,比分再用错一场。
登录后在控制台复制有权使用的 Key,放进服务端环境变量 OPENDATA_API_KEY。文中的 YOUR_API_KEY 只是占位。Key 走查询参数,可能进访问日志,不要写进工单、截图和浏览器前端。打开本页或复制示例不会发出请求。
足球数据 API 的这个操作没有时区参数。日期必须是 YYYYMMDD,不要写成 YYYY-MM-DD。格式错了,网关多半会直接失败;时区用错了,HTTP 照样是绿的,错在你自己的归日逻辑里。
请求日期不是观众的星期四
已验证的 20261008 响应里,UTC 开球横跨 10 月 7 日和 8 日。这不能证明源日历就是 UTC,也不能证明它按观众时区切日,更不能反推「接口内部用了哪一套夏令时规则」。它只说明:按日请求是发现窗口,不是「这一天该出现的全部比赛」。接口没有名为 timezone 的筛选器,也不要自己造一个。跨午夜的场次会同时出现在相邻两次请求里,合并时必须按比赛 id 去重,否则同一场会在日历上画两遍。
三种「空」要拆开看,不能都写成没赛:
- 请求没跑起来:HTTP 4xx/5xx,Key 无效、额度不够或网络中断。凭证和积分只在这一层查。
- 平台拒单:外层是
{code, message, data}。网关code=200才是业务成功,HTTP 200 不够。 - 足球侧跑完了,但仍没有可渲染的列表:
data.status不是"success",response.matches缺失或不是数组,或者数组为空。空的成功列表不等于「全球当天无赛事」,覆盖范围按赛事而定,文档不会替某一天打包票。
get-search-all 配 search=Real Madrid 是带类型的建议检索,不是赛程日历。需要球队或比赛 ID 时再用。已验证的无匹配是 status="success" 且 suggestions=[],那是没命中,不是传输失败,更不能拿来推断日期查询也失败了。
不要按 status.utcTime 字符串前十位分组。每条开球先转时区,再决定它算不算观众的那一天。
先看比赛状态再看比分
主客队对象里都有 score。未开赛的行经常是 0–0。那是占位,不是赛果。分类看标志,不要对比分做算术。
从 status 里读 cancelled、started、finished;如果行上也有同名字段,一并纳入。取消优先——取消场次可能仍带着 0–0,不能当平局进赛果栏目。started=false 且 finished=false 是赛前快照。started=true 且 finished=false 表示已开始、未结束——不是不间断直播的承诺,也不是终场,中场休息和补时都可能停在这个组合上。只有 finished=true 才把比分当完赛。标志缺失或互相打架,状态就是未知,界面上写「待确认」比猜一个结果更诚实。部分完赛行还有 status.scoreStr 和 status.reason,不要假设场场都有。
id 和 leagueId 当主键,按比赛 id 去重。主客各有 id、name、longName、score;缺分不要补零。statusId、tournamentStage、毫秒 timeTS 是附加上下文,用 timeTS 当钟之前先核对嵌套和单位。
若要把赛程里的 id 当作 eventid 再调 get-match-event-detail-by-event-id,比分仍以赛程行为准。已验证的详情响应不含最终比分。
用 zoneinfo 转出本地开球
Python 3.9+,依赖 requests。zoneinfo 需要 IANA 时区数据,环境里没有就装 tzdata。下面脚本只缓存校验通过的成功响应,五分钟是应用层示例,不是接口承诺的更新间隔。缓存键不含凭证。结构不对就抛错,不把「无赛程」打印成成功。相邻三个源日期用来拼 Asia/Shanghai 的 10 月 8 日;同一 id 保留后写入的那条。
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"),
})
要跑才发请求。落盘快照时记下采集时间。相同读请求在用户之间共用。完赛后降低刷新频率,但留一条更正路径。传输失败用有限退避;成功却为空的列表不要当闪断来回打。这些是 GET 快照,不是推送订阅,也不承诺秒级延迟。
按日窗口会漏掉什么
围着 20261008 左右各补一天,只是面向上海的经验垫,不是完备性证明。观众在奥克兰、洛杉矶、伦敦,窗口宽度就不一样:Pacific/Auckland 的深夜场、America/Los_Angeles 的清晨场,都可能落在这个垫子外面。有夏令时的地区用 Europe/London 这类 IANA 名,不要写死 +8,也不要用浏览器本地偏移去猜服务器该怎么切日。相邻日期会多耗额度,合并后仍不代表每项赛事、每个球场、每场改期都进了集合。改期、取消、补赛可能仍停在旧窗口里,新窗口未必立刻出现。
窗口之外的补查按需点名。真正要展示的场次才把 id 传给详情。leagueId 可以交给 get-standing-all-by-league-id;总榜样例用过 leagueid=47,行里有 played、胜平负、scoresStr、goalConDiff、pts、idx。保留返回顺序,不要自编同分规则,也不要把主客场分榜名次当成总排名。球队建议 ID 可交给 get-team-detail-by-team-id,已验证的 teamid=8633 对应皇家马德里。阵容、赔率、分段统计按场次验证,目录里有接口不等于每场有数。
这个操作不会接受时区参数,不会推送实时比分,也不会把空列表解释成足球停摆。把本地日历当完整赛程之前,先看定价上的覆盖、配额和数据使用范围,并以按日期查询参考里的现行参数为准。