跳转到主要内容
本页解释Odds API中使用的核心概念：ID如何构建、实体之间如何关联、时间戳如何使用，以及如何设计可靠的客户端存储。

​
语言前缀

所有端点都以语言代码为前缀：
  • /zh/... (中文)
  • /en/... (英文)
  • /de/... (德文)
翻译字段（例如名称）在可用时遵循前缀语言。 标识符（sportId、fixtureId等）与语言无关。

​
体育、锦标赛、赛季

​
sportId

  • 整数。
  • 嵌入到多个下游ID中的前两位数字。
  • 通过/sports发现。

​
tournamentId

  • 整数。
  • 属于恰好一项体育运动。
  • 通过/tournaments发现。

​
seasonId

  • 整数。
  • 属于恰好一个锦标赛。
  • 通过/seasons发现。

​
盘口和选项

​
marketId和outcomeId之间的关系

盘口和选项在设计上紧密耦合：
  • 盘口代表一个完整的投注市场（例如独赢、1x2、大小球）。
  • 盘口包含多个选项。
  • 属于同一盘口的所有选项共享相同的marketId。
  • 盘口的第一个outcomeId始终等于marketId。
这使得可以无需额外元数据即可确定哪些选项属于哪个盘口。

​
ID结构

marketId和outcomeId都是整数，构造如下： 
{sportId（2位数字）} + {递增数字}
示例：
  • 11xxxx → 篮球盘口或选项
  • 14xxxx → 美式橄榄球盘口或选项
这种设计提供：
  • 每项运动无限的盘口和选项
  • 按运动快速分组
  • 立即可见的盘口关系

​
为什么marketId很重要（套利和建模）

单个marketId下的所有选项共同代表一个完整的概率空间。 这使得marketId特别适用于：
  • 套利检测
  • 超出率/利润率计算
  • 概率归一化
  • 盘口完整性检查
建议： 如果您执行套利或定价逻辑，请始终按marketId对赔率分组。

​
参与者和球员

​
participantId

  • 整数。
  • 代表赛事中的球队或参赛者。
  • 通过/participants发现。

​
playerId

  • 整数。
  • 用于球员投注盘口。
  • playerId = 0通常代表非球员盘口。
  • 通过/players发现。

​
赛事ID

​
fixtureId结构

fixtureId是一个编码多条信息的字符串： 
{providerSlug}{sportId}{tournamentId}{providerFixtureId}
概念示例： 
id1100013262926199
其中：
  • id → 提供商标识符/简短slug
  • 11 → sportId（2位数字）
  • 000132 → tournamentId（6位数字）
  • 62926199 → 提供商的原生赛事ID

​
这为什么重要

仅从fixtureId，您就可以推断：
  • 体育运动
  • 锦标赛
  • 上游提供商
  • 全局唯一性
这使得日志记录、调试、分析和跨系统关联更加简单和可靠。

​
期货ID

​
futureId结构

futureId遵循类似的原则： 
{providerSlug}{sportId}{seasonId}{marketId}
这编码了：
  • 提供商
  • 体育运动
  • 赛季
  • 盘口
与fixtureId一样，这使期货：
  • 全局唯一
  • 自描述
  • 易于调试和追踪

​
赔率标识符

​
赛事赔率键

对于赛事，单个价格由以下唯一标识： 
{fixtureId}:{bookmaker}:{outcomeId}:{playerId}
示例： 
id1400003160574217:bet365:141:0
此组合唯一定义一个价格。

​
期货赔率ID

对于期货，赔率由以下唯一标识： 
{futureId}:{bookmaker}:{outcomeId}:{participantId}:{playerId}
这完全指定了：
  • 期货
  • 博彩公司
  • 选项
  • 参与者（如适用）
  • 球员（用于投注）

​
存储建议（重要）

我们强烈建议使用这些标识符作为存储中的主键： 赛事赔率： 
{fixtureId}:{bookmaker}:{outcomeId}:{playerId}
期货赔率： 
{futureId}:{bookmaker}:{outcomeId}:{participantId}:{playerId}
这保证了：
  • 无重复
  • 简单更新
  • 高效的时间序列存储
  • 跨快照和回填的轻松协调

​
时间戳（秒与毫秒）

此API有意使用纪元秒和纪元毫秒，具体取决于上下文。

​
纪元秒（UTC）

用于计划或粗粒度时间值：
  • startTime
  • startTimeFrom
  • startTimeTo

​
纪元毫秒（UTC）

用于高频价格更新：
  • changedAt
  • 赛事的赔率since过滤器
  • 期货赔率createdAt

​
建议

  • 将时间戳存储为整数。
  • 不要在文档记录为秒的地方假设毫秒（反之亦然）。
  • 仅在需要时进行内部归一化。

​
实施建议

​
服务器位置很重要

要实现实时更新的最低延迟：
  • 最快的交付区域是中欧（推荐）和美国东部。
  • 为获得最佳性能，请将后端部署在我们使用的相同数据中心，例如：
  • 如果您正在构建对延迟敏感的预测市场或模型，请考虑：
    • 通过Netcup部署在奥地利(AT)，或
    • 使用AWS eu-west-1（爱尔兰）
与我们流媒体基础设施位于同一位置的服务器可以更快地接收更新，跳数更少。

​
快照 + 实时模式

可靠的集成模式：
  1. 获取HTTP快照（赛事、赔率或期货）
  2. 订阅WebSocket以获取实时更新
  3. 如果WebSocket发出snapshot_required信号：
    • 重新获取HTTP快照
    • 恢复实时流

​
高效回填

  • 在可用时使用since参数
  • 除非需要，否则避免完整的历史获取
  • 按赔率标识符存储赔率以进行去重

​
速率限制处理

  • 读取X-RateLimit-Limit、X-RateLimit-Remaining和X-RateLimit-Reset
  • 在HTTP 429时，遵守Retry-After并退避

​
总结

此API的设计使得：
  • ID是自描述的
  • 关系无需连接即可推导
  • 赔率标识符是全局唯一的
  • 套利和存储逻辑简单且稳健
围绕这些原则建模您的系统将产生快速、可维护和面向未来的集成。