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

​
语言前缀

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

​
体育、锦标赛、赛季

​
sportId

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

​
tournamentId

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

​
seasonId

  • 整数。
  • 属于恰好一个锦标赛。
  • 通过/seasons发现。
完整的运动覆盖表列出了每个 sportId 及其是否以赛事、期货或两者形式提供。

​
盘口和选项

摘要 —— 每个选项都遵循固定层级：marketType → period → handicap → side，全部编码进 outcomeId —— 因此同一个投注始终解析为相同的 marketId / outcomeId，通过坐标定位而非对博彩公司名称做字符串匹配。唯一不在 outcomeId 中的是球员，由 playerId 承载。同一盘口的所有选项共享其 marketId，即该盘口的首个 outcomeId。

​
盘口如何分解（确定性层级）

每一个 outcomeId 都由单一、确定性的分解逻辑生成 —— OddsPapi 将每个盘口拆分为固定层级： 
marketType（盘口类型）→ period（赛段）→ handicap（盘口线 / specifier）→ side（选项）   [+ 可选 player]
因此”全场总进球大于 2.5”在不同博彩公司和不同赛事中始终落在相同的 marketId / outcomeId 上。
层级字段含义
1marketType盘口种类（1x2、totals、spreads、spreads-european、bothteamsscore、drawnobet、oddeven 等）。
2period盘口适用的赛段（fulltime、p1、p2）。
3handicap盘口线 / specifier（例如 2.5、-0.25）。每个不同的盘口线都是独立的 marketId。 无盘口线的盘口（如 1x2）为 0.0。
4outcomeName盘口的选项方向（Over / Under、1 / X / 2、Yes / No 等）。
关键规则： 由于每个盘口线都有自己的 marketId，“大于 2.5” 和 “大于 3.5” 是不同的盘口 —— 而非同一盘口的两个选项。在单个 marketId 内，选项仅为该确切盘口线的各个方向（例如 Over 2.5 + Under 2.5）。
真实足球盘口映射的代表性切片。每个 marketId 等于其首个 outcomeId，且每个盘口线都是独立的盘口：
marketIdmarketNamemarketTypeperiodhandicapoutcomeIdoutcomeName
101Full Time Result1x2fulltime0.01011
101Full Time Result1x2fulltime0.0102X
101Full Time Result1x2fulltime0.01032
104Both Teams To Scorebothteamsscorefulltime0.0104Yes
104Both Teams To Scorebothteamsscorefulltime0.0105No
106Over Under Full Timetotalsfulltime0.5106Over
106Over Under Full Timetotalsfulltime0.5107Under
1010Over Under Full Timetotalsfulltime2.51010Over
1010Over Under Full Timetotalsfulltime2.51011Under
1068Asian Handicapspreadsfulltime-0.510681
1068Asian Handicapspreadsfulltime-0.510692
10122European Handicapspreads-europeanfulltime6.0101221
10122European Handicapspreads-europeanfulltime6.010123X
10122European Handicapspreads-europeanfulltime6.0101242
10208First Half Result1x2p10.0102081
10208First Half Result1x2p10.010209X
10208First Half Result1x2p10.0102102
10214Draw No Betdrawnobetfulltime0.0102141
10214Draw No Betdrawnobetfulltime0.0102152
10222Odd Even Full Timeoddevenfulltime0.010222Odd
10222Odd Even Full Timeoddevenfulltime0.010223Even
10224Over Under Team 1teamtotals-team1fulltime0.510224Over
10224Over Under Team 1teamtotals-team1fulltime0.510225Under
读取第一行：marketType=1x2、period=fulltime、handicap=0.0、outcomeName=1 —— 即全场比赛结果盘口的主队方向。

​
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}（赛事）或 {futureId}:{bookmaker}:{participantId}（期货）唯一标识。请将这些 oddsId 字符串用作存储中的主键，以实现干净的去重、更新与对账。

​
赛事赔率键

对于赛事，单个价格由以下唯一标识： 
{fixtureId}:{bookmaker}:{outcomeId}:{playerId}
示例： 
id1400003160574217:bet365:141:0
此组合唯一定义一个价格。 去掉 bookmaker，剩下的就是选项本身 —— {fixtureId}:{outcomeId}:{playerId} —— 这是与博彩公司无关的评级 / 结算键，因为一个选项在任何博彩公司处的输赢都相同。无需 marketId；outcomeId 已编码了盘口。

​
期货赔率ID

对于期货，赔率由以下唯一标识： 
{futureId}:{bookmaker}:{participantId}

​
时间戳（秒与毫秒）

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

​
纪元秒（UTC）

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

​
纪元毫秒（UTC）

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

​
建议

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

​
运营提示

​
服务器位置很重要

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

​
快照 + 实时模式

可靠的集成模式：
1

获取 HTTP 快照

通过 REST 拉取当前状态（赛事、赔率或期货）。
2

订阅 WebSocket

在快照之上流式接收实时更新。
3

按信号重新获取快照

如果 WebSocket 发出 snapshot_required 信号，请重新获取 HTTP 快照并恢复实时流。

​
高效回填

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

​
速率限制

有关请求头、各端点限制以及 429 退避处理，请参阅速率限制。

​
历史赔率与 CLV

实时 WebSocket 的 odds 和 oddsFutures 频道传输的是最新状态 —— 它们针对低延迟交易进行了优化，在负载下会合并或丢弃中间更新，并非逐笔账本。
使用实时数据流进行交易，使用 REST 历史端点进行衡量 —— CLV 模型、成交审计和回测。
当您需要某个结果的完整价格变动，或其开盘价与收盘价时，请使用 REST 历史端点。它们与实时 odds 频道共享相同的 oddsId 格式（{fixtureId}:{bookmaker}:{outcomeId}:{playerId}），因此您可以将实时成交直接关联到其历史记录和收盘价记录。
用途赛事（Fixtures）期货（Futures）
完整价格时间线GET /fixtures/odds/historicalGET /futures/odds/historical
开盘价与收盘价（OLV/CLV）GET /fixtures/odds/clvGET /futures/odds/clv
交易用例：
  • CLV 建模 —— 将您的成交价与收盘价进行比较，以衡量优势。
  • 成交审计 —— 将成交价格与已记录的时间线进行核对，以检测滑点。
  • 回测 —— 重放完整的历史时间线，以根据真实的价格变动测试策略。
完整的请求参数、响应结构以及每个端点的交互式演练，请参阅 API → 参考 部分。

​
术语表

API 中常用核心术语的快速定义。 标识符与数据模型
  • sportId —— 运动数字标识符；下游 marketId、outcomeId 和 fixtureId 的前两位数字。
  • fixtureId —— 单场比赛/事件的字符串键，编码提供商、运动、赛事和提供商赛事 ID。
  • futureId —— 期货 / 冠军盘口的字符串键，编码提供商、运动、赛季和盘口。
  • marketType —— 盘口种类（1x2、totals、spreads、bothteamsscore 等）。
  • period —— 盘口适用的赛段（fulltime、p1、p2）。
  • handicap —— 盘口线 / specifier；每个不同的盘口线都是独立的 marketId。
  • marketId —— 将一个盘口所有选项分组的整数；等于盘口的首个 outcomeId。
  • outcomeId —— 标识一个完全分解后的选择的整数：marketType + period + handicap（盘口线）+ 方向。它编码了除球员以外的一切 —— 球员由 playerId 补充。
  • playerId —— 在球员盘口中将选项关联到某个球员；playerId = 0 为非球员盘口。
  • participantId —— 标识赛事中球队或参赛者的整数。
  • oddsId —— 价格复合键。赛事：{fixtureId}:{bookmaker}:{outcomeId}:{playerId}。期货：{futureId}:{bookmaker}:{participantId}。
价格与交易
  • OLV —— 开盘线价值：选项的首个记录价格。
  • CLV —— 收盘线价值：选项结算前的最后价格；评估执行质量的基准。
  • staleOdds —— 表示某博彩公司连接降级、其赔率可能并非最新的标志。
  • settlement（结算） —— 赛后端点，返回逐结果的结果（赢 / 输）、最终比分和盈亏幅度。
流式传输与交付
  • serverEpoch + entryId —— 每频道游标；serverEpoch 变化表示客户端必须重新获取快照。
  • resume / replay（恢复 / 重放） —— 在 resumeWindowMs（默认 60000）内重连并重放丢失的消息。
  • snapshot_required —— 表示游标已超出恢复窗口、需重新获取 REST 快照的信号。