# GoalXData Football API 接口目录

基础地址：`https://goalxdata.com/api/v1/football`

## 目录

1. `GET /capabilities`
2. `GET /competitions`
3. `GET /competitions/{id}`
4. `GET /seasons`
5. `GET /seasons/{id}`
6. `GET /teams`
7. `GET /teams/{id}`
8. `GET /players`
9. `GET /players/{id}`

## 当前比赛与详情

10. `GET /matches`
11. `GET /matches/{id}`
12. `GET /matches/{id}/modules`
13. `GET /matches/{id}/modules/{module}`
14. `GET /matches/{id}/post-match-news`
15. `GET /standings`
16. `GET /squads`
17. `GET /team-season-metrics`
18. `GET /player-season-metrics`

## 高级赔率

19. `GET /pregame-index`
20. `GET /matches/{id}/pre-match-index`
21. `GET /matches/{id}/pre-match-index/opening-closing`（独立历史赔率权限）
22. `GET /matches/{id}/pre-match-index/history`（旧 Key 兼容，已弃用）
23. `GET /matches/{id}/in-play-index`（独立滚球权限）
24. `POST https://goalxdata.com/api/v1/realtime/ticket`（赔率 WebSocket 正式商业版票据）

高级赛前赔率和滚球赔率是高级赔率附加包内两个独立授权的产品，只返回已唯一配对、通过新鲜度校验的正式数据，允许最快每 2 秒读取。历史赔率也是独立附加包，只提供全场进球数、让球盘、胜平负的出盘与临场，不提供中间变化。每个 Key 的全部赔率 REST 共用独立 `OddsGlobal` 额度池，每小时 4,000 次；普通 REST 使用另一个 `Global` 额度池，每小时 4,000 次，均不设每秒限制。公司覆盖口径为 18 家，但逐场按市场实际可用返回，可能不齐全，不承诺固定公开代码表。字段口径为“市场 → 指数 → 赔率”。每个 HTTP 请求只计 1 次，响应记录数不另计次；赛程复核暂停不算失败。

WebSocket 正式商业版通过票据连接 `wss://stream.goalxdata.com/v1/odds`：创建票据计普通 REST 1 次，推送消息不计 REST 次数；每个 Key 最多 2 条连接、每条 1–100 场。24 小时只承诺恢复最新状态；缺口不超过 2,000 个匹配事件时无缺口续传，超限发送 `resume_reset` 和最新快照。赛前与赛中频道分别要求对应附加包。只读服务状态为 `GET https://stream.goalxdata.com/health`。

以下赔率路径已从客户 API 移除并返回 `404`：

- `/api/v1/football/odds/reference`
- `/v1/football/odds/stream`

## 历史比赛数据

25. `GET /history/matches`
26. `GET /history/matches/{id}`
27. `GET /history/matches/{id}/modules`
28. `GET /history/matches/{id}/modules/{module}`
29. `GET /history/team-season-metrics`
30. `GET /history/player-season-metrics`

历史权限仅扩展赛事、比赛和详情读取范围，不恢复已移除的其他赔率接口。

## 时间与响应

- 所有响应使用固定 JSON 信封。
- `meta.timezone` 固定为 `Asia/Shanghai`。
- `meta.utcOffset` 固定为 `+08:00`。
- 所有时间点使用带 `+08:00` 的 ISO 8601 字符串。