为什么需要赛事数据 API做体育类应用、数据分析或自动化推送时第一道坎往往不是业务逻辑而是数据源。自己爬网页要面对反爬、页面改版、时区混乱、字段缺失等问题。一个结构稳定的 HTTP API 能把这些问题收敛掉让开发者专注在业务侧。本文以极数本源篮球赛事 APIhttps://apizero.cn/marketplace/basketball为例完整走一遍从读文档、调通接口到封装 SDK 的流程。接口覆盖 NBA、WNBA、NCAA 男篮、CBA返回开赛时间、比分、比赛状态与场馆不含赔率或门票适合资讯展示类场景。接口速览先建立一张全局认知表后面所有代码都围绕它展开。项目值请求地址https://v1.apizero.cn/api/basketball请求方式POST也支持 GET 形式传参参数格式FORM / QUERY / JSON返回格式application/json鉴权方式Authorization: Bearer API Key免费额度登录后 20 次/日QPS 40请求头鉴权是主推方式同时兼容X-API-Key以及 Query 参数api_key/apikey/key其中key仅在值为sk_live_/sk_test_/sk_stag_形态时生效。生产环境请只用请求头把 Key 放进 URL 会留在日志和浏览器历史里。请求参数参数类型必填说明datestring否比赛日期YYYY-MM-DD或YYYYMMDD缺省为北京时间当日limitint否返回条数1–200缺省 80注意date是北京日期不是 UTC。这意味着你在服务器上做定时任务时不能直接用datetime.utcnow().date()否则跨零点会查错比赛日。返回结构顶层是统一的code/msg/data/tips信封data里分两部分summary本次查询的元信息含sport、date、league、status、count、total、live、generated_atmatches场次数组排序规则是进行中 → 未开赛按时间 → 已结束单场比赛的关键字段{ id: 401810001, league_name: NBA, start_at: 2026-09-11 09:00:00, status: finished, home: { name: Los Angeles Lakers, short: LAL, score: 112 }, away: { name: Golden State Warriors, short: GSW, score: 108 } }status只有三个枚举值live、upcoming、finished前端可以直接映射成样式不需要自己猜状态字符串。用 curl 先跑通在写任何代码之前先用最短路径验证 Key 和网络。curl -X POST https://v1.apizero.cn/api/basketball \ -H Authorization: Bearer sk_live_xxxxxxxx \ -H Content-Type: application/json \ -d {date: 2026-09-11, limit: 80}如果返回code: 0说明链路通。若返回鉴权失败按顺序检查Key 是否带了Bearer前缀、是否有多余空格、是否是已激活的套餐。免费用户未携带 Key 时每天只有 5 次、QPS 1很容易误判为接口故障。封装一个 Python SDK直接用requests散落调用会带来三个问题重复的鉴权代码、无重试、无类型提示。下面封装一个轻量客户端。依赖与基础客户端# basketball_client.py from __future__ import annotations import time import logging from dataclasses import dataclass from datetime import datetime, timedelta, timezone from typing import Any import requests logger logging.getLogger(__name__) BASE_URL https://v1.apizero.cn/api/basketball BEIJING_TZ timezone(timedelta(hours8)) class ApiZeroError(RuntimeError): 接口返回 code ! 0 时抛出。 def __init__(self, code: int, msg: str): super().__init__(f[{code}] {msg}) self.code code self.msg msg dataclass class Team: name: str short: str | None score: int | None dataclass class Match: id: str league_name: str start_at: str status: str home: Team away: Team property def is_live(self) - bool: return self.status live property def display(self) - str: hs self.home.score if self.home.score is not None else - as_ self.away.score if self.away.score is not None else - return f{self.home.short or self.home.name} {hs} : {as_} {self.away.short or self.away.name}核心请求逻辑关键点是把「北京日期」的计算固化到客户端内部业务侧永远不用关心时区同时加上指数退避重试只对网络错误和 5xx 重试不对 4xx 重试——参数错了重试一百次也没用。class BasketballClient: def __init__(self, api_key: str, timeout: int 10, max_retries: int 3): if not api_key: raise ValueError(api_key 不能为空) self.api_key api_key self.timeout timeout self.max_retries max_retries self._session requests.Session() self._session.headers.update({ Authorization: fBearer {api_key}, Content-Type: application/json, Accept: application/json, }) staticmethod def beijing_today() - str: 接口的 date 参数是北京日期不要用 UTC。 return datetime.now(BEIJING_TZ).strftime(%Y-%m-%d) def _post(self, payload: dict[str, Any]) - dict[str, Any]: last_exc: Exception | None None for attempt in range(1, self.max_retries 1): try: resp self._session.post(BASE_URL, jsonpayload, timeoutself.timeout) # 4xx 是客户端问题直接抛出不重试 if 400 resp.status_code 500: resp.raise_for_status() resp.raise_for_status() body resp.json() if body.get(code) ! 0: raise ApiZeroError(body.get(code, -1), body.get(msg, unknown)) return body[data] except ApiZeroError: raise except (requests.ConnectionError, requests.Timeout, requests.HTTPError) as exc: last_exc exc # 429 限流需要更长的冷却 wait 2 ** attempt if isinstance(exc, requests.HTTPError) and exc.response is not None \ and exc.response.status_code 429: wait 5 * attempt logger.warning(第 %d 次请求失败%s%.1fs 后重试, attempt, exc, wait) if attempt self.max_retries: time.sleep(wait) raise RuntimeError(f请求失败已重试 {self.max_retries} 次) from last_exc def fetch_matches(self, date: str | None None, limit: int 80) - list[Match]: if not 1 limit 200: raise ValueError(limit 必须在 1–200 之间) data self._post({date: date or self.beijing_today(), limit: limit}) return [self._parse_match(m) for m in data.get(matches, [])] staticmethod def _parse_match(raw: dict[str, Any]) - Match: def to_team(obj: dict[str, Any]) - Team: return Team( nameobj.get(name, ), shortobj.get(short), scoreobj.get(score), ) return Match( idstr(raw.get(id, )), league_nameraw.get(league_name, ), start_atraw.get(start_at, ), statusraw.get(status, ), hometo_team(raw.get(home, {})), awayto_team(raw.get(away, {})), )这里有个容易踩的坑score在upcoming状态下可能缺失或为 0。上面用obj.get(score)保留None前端就能区分「0 分」和「还没开始」。落地场景一每日赛程看板把当天的比赛按状态分组是资讯类页面最常见的需求。def render_board(client: BasketballClient, date: str | None None) - str: matches client.fetch_matches(datedate, limit200) groups: dict[str, list[Match]] {live: [], upcoming: [], finished: []} for m in matches: groups.setdefault(m.status, []).append(m) lines: list[str] [] title {live: 进行中, upcoming: 未开赛, finished: ✅ 已结束} for key in (live, upcoming, finished): items groups.get(key) or [] if not items: continue lines.append(f\n{title[key]}{len(items)} 场) for m in items: lines.append(f [{m.league_name}] {m.start_at} {m.display}) return \n.join(lines) or 今日暂无比赛 if __name__ __main__: import os client BasketballClient(os.environ[APIZERO_KEY]) print(render_board(client))运行前设置环境变量export APIZERO_KEYsk_live_xxx。永远不要把 Key 硬编码进仓库。落地场景二实时比分轮询live字段告诉你当前有几场进行中。做实时看板时只需要在存在进行中场次时提高轮询频率否则降到低频这样能显著节省免费额度。def watch(client: BasketballClient, interval_live: int 30, interval_idle: int 600): 有直播时 30s 轮询否则 10 分钟一次。注意免费额度 20 次/日。 last_snapshot: dict[str, tuple[int | None, int | None]] {} while True: matches client.fetch_matches(limit200) live [m for m in matches if m.is_live] for m in live: cur (m.home.score, m.away.score) if last_snapshot.get(m.id) ! cur: print(f比分更新 {m.display} ({m.start_at})) last_snapshot[m.id] cur time.sleep(interval_live if live else interval_idle)免费方案每天 20 次30 秒轮询会在 10 分钟内耗尽额度。生产环境建议本地缓存 只在summary.live 0时短轮询或直接升级到黄金会员4,000 次/日、QPS 80。工程化注意事项缓存策略赛程数据的时间局部性很强已结束的比赛不会变未开赛的比赛只有start_at可能微调。可以按「日期 状态」做分层缓存finished缓存 24 小时几乎不用再查upcoming缓存 10 分钟live缓存 15–30 秒时区统一接口返回的start_at已经是北京时间字符串不要再做二次时区转换。如果前端要按用户本地时区展示应在浏览器侧解析而不是在服务端改动原始值。错误处理清单现象可能原因处理方式鉴权失败未带 Key / Key 失效 / 免费额度用尽检查请求头确认套餐状态429超出 QPS 或日额度指数退避降低轮询频率code ! 0参数非法校验date格式与limit范围数据为空该日确无比赛如休赛期按空态展示不要当错误免责声明的工程含义官方明确说明赛程与比分来自公开体育数据源可能有延迟或漏场CBA 为独立备源覆盖可能少于 NBA仅供资讯展示不构成投注建议。落到代码上就是两点不要把它当作强一致数据源做资金类决策以及前端必须展示数据延迟提示。小结本文从接口文档出发完成了三件事理清了鉴权、参数与返回结构尤其是date是北京日期这个易错点封装了一个带类型提示、指数退避和 429 特殊处理的可运行 SDK给出赛程看板与实时轮询两个落地场景并讨论了缓存、时区与额度控制接口本身不复杂真正决定项目稳定性的往往是这些工程细节。把 SDK 抽出来之后业务层只需要调client.fetch_matches()剩下的时区、重试、解析都由客户端兜住。