TRUST · 透明承诺

你看到的每一个数
来自哪里

PitchLab 不接受"行业惯例不公开数据来源"。这一页列出每一个字段、每一秒的爬取频率、每一次的回填批次。 你可以一眼看到我们到底依赖谁。

FIELD MATRIX · 字段裁定

4 色分布

已落库

spike 中

未上线

NO-GO

共 27 个核心字段 · 数据快照 W2 D4 · 2026-04-30

HEALTH · 服务健康

实时状态

ALL GREEN

PGPostgreSQL 18.0up
REDIS8.0.5 · db=5 · keys=504ms

快照 · 2026-05-14 14:52:09 UTC · CHECK #932

REAL-TIME SOURCE HEALTH · D4.4 监控

实时数据源健康 (5min 刷新)

每 5 分钟 cron-source-health worker 探测每个主源的最新数据延迟。下表是当前快照。stale 表示数据存在但超过预期更新周期 (TM 周更, FotMob 30s)。

数据加载失败: Failed query: WITH latest AS ( SELECT source, MAX(checked_at) as last_check FROM data_source_health GROUP BY source ) SELECT h.source, h.status, h.checked_at::text as last_check, h.latency_ms, h.rows_seen, (h.raw_json->>'last_seen')::text as last_data_at FROM data_source_health h JOIN latest l ON l.source = h.source AND l.last_check = h.checked_at ORDER BY h.source params:

数据源: data_source_health · 由 cron-source-health (pm2) 每 5 min 写入

DATA SOURCES · 12 源混合

为什么是 12 个源不是 1 个

单个 API 永远撑不起一个真正深度的足球数据站。我们在 HK 主项目 + JP 爬虫双 VPS 架构下，组合 12 个源，覆盖实时赛程 / 历史 30 年 / 球员资料 / xG / 工业级事件流 / 跨源 ID 映射。所有源公开可查，license 全部 CC0 / MIT / 公开 API。

L1 主干· 公开 API

ESPN Public API

实时赛程 + 比分 + 阵容 + 标准事件 (250 联赛全球覆盖)

覆盖: 250 联赛 (五大联赛 + UCL/UEL/UECL + 中超/J1/MLS/沙特联等)

规模: scoreboard 2-15min cron

状态: 10/5 联赛实测 200

L2 历史· CC0

football-data.co.uk

30+ 年历史比分 + 10 家书 odds + 射门/角球/卡片

覆盖: 23 联赛 (英苏德意西法荷比葡土希)

规模: 8830 fixtures (5 大联 5 季)

状态: 已 import

L3 球员资料· CC0

Transfermarkt (Kaggle)

球员身价 + 合同 + 转会历史 + 伤病时间线

覆盖: 92K 球员 / 1.1M 转会 / 143K 伤病

规模: weekly 自动更新

状态: 脚本就位, 等 KAGGLE_KEY

L4 兜底· CC0

openfootball/football.json

公共域 fixture 骨架 (防 ESPN 突然下线)

覆盖: 20 联赛 25-26 + 历史回到 2014/15

规模: 6784 matches (当前赛季)

状态: 已 import

L5 datalake· 需联系作者

salimt/football-datasets

Transfermarkt 历史深度 dump (一次性)

覆盖: 92K 球员 + 1.8M 球员表现

规模: 5.6M 总行 / 一次性

状态: 暂留备用

L6 ID 映射· 公开

withqwerty/reep

跨源球员/球队/联赛 ID 映射 (解决 Mohamed Salah ↔ M. Salah)

覆盖: 25+ 源 (TM/FBref/Sofascore/Flashscore/Opta/ESPN/UEFA/Wikidata)

规模: 519K 行映射 / 68MB

状态: 已 import

L7 工业级· CC BY-NC

StatsBomb open-data

完整事件流 + freeze-frame 360 全场员位置 + xG (FotMob 都没有)

覆盖: 76 competition-season (五大联部分 + UCL 1970-2018 + WC 1958-2022 + Euro)

规模: 75 赛季 / 3464 matches

状态: matches list 已落 (events 按需 ~3GB)

L8 高级 stats· TLS spoof 公开数据

Sofascore (curl_cffi)

球员 rating + 触球 + 传球率 + h2h + incidents 细分

覆盖: 17 联赛 (五大 + 中日韩澳印 + 欧战)

规模: 225 matches 50MB (EPL 测试拉)

状态: JP 爬虫实测 6 endpoint × 225 场

L9 高级 stats· Sports Reference 公开

FBref via ScraperFC

39 联赛 league_table + per-player 35+ 字段 (传球/触球/抢断/PSxG)

覆盖: EPL 1888→今 (137 季) + 五大联赛全

规模: 5 大联赛 24-25 league_table 已拉

状态: JP 爬虫 (botasaurus + Chrome xvfb)

L10 比赛聚合· 公开 endpoint

FotMob /api/data/leagues

rating + xG + 比赛聚合 + lineup

覆盖: 12 联赛 (五大 + UCL/UEL + MLS/中超/J1/K1/沙特联)

规模: 10/12 联赛 13.2MB

状态: JP 爬虫实测 200

L11 shot-level xG· 公开 HTML

Understat

shot-level xG (英西意德法俄, 自 2014)

覆盖: 6 联赛 EPL/西甲/德甲/意甲/法甲/俄超

规模: —

状态: IDC IP HTML stripped, 暂跳过

L12 球队 Elo· 公开 CSV

ClubElo

球队 Elo 历史 1946→今 (任何源都没有的纵向力量评估)

覆盖: 200+ 球队 / 平均 50 年/队

规模: —

状态: VPS 端口 80 出站被拦, 暂跳过

8 live · 2 ready · 2 skipped · 总 12 源

DATA PIPELINE · 数据流水线

从权威数据源到你的浏览器，4 层

L0 RAW·原始落盘

全量原始 JSON 存档

Postgres + S3
保留 2 年

当前 4.2TB

L1 ODS·标准化

字段类型 · ID 映射

34 张主表
每日 02:00 重建

1,184 联赛

L2 DWD·业务计算

xG · 评分 · 进打 · 趋势

72 张派生表
比赛级 hook

482K 球员

L3 ADS·应用聚合

前台 API 视图

24 张物化视图
15min 刷新

200ms 命中

完整数据架构L0-L3 详解 →

完整数据架构 · L0-L3 详解 →

FIELD DETAILS · 字段明细

字段裁定明细 · 27 项

分类	字段	来源	状态	备注
比赛核心	比分 / 主客队 / 状态	/fixtures.goals + .teams	已落库	L1 PG · MUN 2-1 Brentford 已实测
比赛核心	进球事件 (球员/分钟)	/fixtures/events	已落库	L1 PG fixture_events
比赛核心	黄红牌 / 换人事件	/fixtures/events.type	已落库	L1 PG fixture_events
球员	首发阵容 + 替补	/fixtures/lineups	已落库	L1 PG fixture_lineups
球员	球员评分 (权威 API)	/fixtures/players.statistics.games.rating	已落库	L1 PG fixture_players
球员	射门/传球/抢断 (per player)	/fixtures/players.statistics	已落库	L1 PG fixture_players JSON
团队统计	控球率 / 射门 / 角球 / 越位	/fixtures/statistics	已落库	L1 PG fixture_statistics
积分榜	联赛积分榜 (含进球差/形态)	/standings	已落库	L1 PG standings · PL 2024-25 已 import
伤病	赛前伤病名单	/injuries	已落库	L1 PG injuries · 60 records
联赛	赛程表 (round/season)	/fixtures?league=&season=	已落库	L1 PG fixtures
联赛	球队 logo / 主场	/teams	已落库	L1 PG teams
进阶数据	xG (预期进球)	API 字段未确认	spike 中	T-P05-02 spike · 双轨 (API 给则用, 否则我方用 StatsBomb 公开模型)
进阶数据	xG 时间轴 (per minute)	依赖 xG	spike 中	Phase 2 候选
进阶数据	球员热区图	/fixtures/players (含坐标?)	spike 中	T-P05-02 spike
进阶数据	PPDA (压迫强度)	需逐传球事件 + 坐标	spike 中	Phase 2 候选, 我方计算
进阶数据	传球网络	需逐传球起止坐标	spike 中	Phase 3 候选
球员	球员历史赛季统计	/players?season=	spike 中	Phase 1 末批量 import
比赛	VAR 判罚详情	/fixtures/events 部分	spike 中	API 不稳定 · 部分场次缺
球员	球员市场价值	/players (无原生)	spike 中	需 Transfermarkt 或 Sofascore 二级源
团队	教练战术倾向	无原生 API	未上线	Phase 3+ AI 抽取自文字
团队	球队赛季 form	可从 fixtures 聚合	未上线	Phase 2 计算
用户	评论 / 评分	我方 UGC	未上线	Phase 4+
用户	投注赔率	/odds	未上线	Phase 4+ 合规审查后
联赛	次级联赛覆盖	/leagues	未上线	Phase 5+ 程序化
进阶数据	防线高度 (defense line)	API 不给	NO-GO	Phase 4+ 评估或砍
进阶数据	球员体能 GPS	API 不给	NO-GO	需赛事方授权, 商业不可行
媒体	完整集锦视频	版权	NO-GO	fair use 仅嵌入第三方

CONTRACT · 信任契约

不变红线 · 4 条

✓不硬造、不硬凑 · API 没有的字段标灰或红，绝不编造数字
✓L0 RAW 全量落盘 · 原始 JSON 一字节不丢，可追溯每个数字
✓AI 只在后台做脏活 · 前台所有 AI 内容标 badge + 来源
✓黄字段先 spike · 不上"先发再说"，做完才上线