GET historical-odds

端点

GET /v4/historical-odds

请求参数

• fixtureId* (string) — 要获取历史赔率的比赛 ID。
• bookmakers* (string) — 以逗号分隔的博彩公司 slug 列表（最多 3 个）用于过滤结果。例如：pinnacle,bet365
• id (number) — （可选）用于过滤的特定历史赔率记录的唯一 ID。
• playerId (number) — （可选）与赔率关联的 playerId，用于缩小结果范围。
• outcomeId (number) — （可选）用于过滤特定结果（outcome）赔率的 outcomeId。
• active (boolean) — （可选）根据该历史记录当前是否仍然有效进行过滤。

请求头

• If-None-Match (string) — （可选）回传上一次响应中的 ETag，以发起条件请求。如果响应内容完全相同，服务器将返回 304 Not Modified 及空响应体，而不是重新发送整个负载。仅对已结束或已取消的赛事生效（参见下文"条件请求"）。

请求示例

GET /v4/historical-odds?fixtureId=id1000000758265379

响应示例

{
  "fixtureId": "id1000000758265379",
  "bookmakers": {
    "pinnacle": {
      "markets": {
        "101": {
          "outcomes": {
            "101": {
              "players": {
                "0": [
                  {
                    "createdAt": "2025-04-16T21:12:10.506331+00:00",
                    "price": 9.11,
                    "limit": 1191.25,
                    "active": false,
                    "exchangeMeta": null
                  },
                  {
                    "createdAt": "2025-04-16T20:50:58.321847+00:00",
                    "price": 9.11,
                    "limit": 1191.25,
                    "active": true,
                    "exchangeMeta": null
                  }
                ]
              }
            }
          }
        },
        "10168": {
          "outcomes": {
            "10168": {
              "players": {
                "0": [
                  {
                    "createdAt": "2025-04-16T20:16:45.057806+00:00",
                    "price": 1.729,
                    "limit": 13072.7023319616,
                    "active": false,
                    "exchangeMeta": null
                  },
                  {
                    "createdAt": "2025-04-16T20:16:18.597131+00:00",
                    "price": 1.729,
                    "limit": 13072.7023319616,
                    "active": true,
                    "exchangeMeta": null
                  },
                  {
                    "createdAt": "2025-04-16T20:15:51.441377+00:00",
                    "price": 1.699,
                    "limit": 13633.7625178827,
                    "active": true,
                    "exchangeMeta": null
                  }
                ]
              }
            }
          }
        }
      }
    }
  }
}

响应 (200 OK)

当请求成功时，服务器会返回状态码 200 并返回一个从 fixtureId 到嵌套博彩公司赔率历史的映射。.

• bookmakers (object) — 按博彩公司 slug 分组的赔率历史
  • markets (object) — 每场比赛包含带有结果（outcomes）的市场对象。
  • outcomes (object) — 带有球员数据的结果 ID。
  • players (object) — 包含赔率数据的球员信息，包括：:
    • id (number) — 历史赔率记录的唯一标识符。
    • createdAt (string) — 创建该历史赔率记录时的时间戳。
    • price (number) — 当时提供的价格（赔率）。
    • limit (number) — 当时该赔率允许的最大投注额。
    • active (boolean) — 指示该历史记录在当时是否处于激活状态。
    • exchangeMeta (object|null) — 如适用，包含交易所 back / lay 价格等元数据。

响应头（仅限已结束/已取消的赛事）

• ETag — 用于标识当前响应体的简短不透明字符串。例如： "a1b2c3d4e5f6a7b8".
• Cache-Control — private, max-age=259200 （3 天）。

响应 (304 Not Modified)

当请求包含的 If-None-Match 头的值与当前该赛事和筛选组合的 ETag 相匹配时返回。响应体为空；客户端应重新使用之前缓存的负载。

条件请求

对于已结束或已取消的赛事，响应是确定性的，因此每个 200 响应都包含 ETag 头。反复轮询同一赛事的客户端可以在本地缓存响应体，然后在后续请求中发送 If-None-Match: <etag>，以避免重新传输和解析未变化的负载：

GET /v4/historical-odds?fixtureId=id1000000758265379&bookmakers=pinnacle
→ 200 OK
  ETag: "a1b2c3d4e5f6a7b8"
  Cache-Control: private, max-age=259200
  { "fixtureId": "...", "bookmakers": { ... } }

GET /v4/historical-odds?fixtureId=id1000000758265379&bookmakers=pinnacle
If-None-Match: "a1b2c3d4e5f6a7b8"
→ 304 Not Modified
  ETag: "a1b2c3d4e5f6a7b8"

ETag 与具体响应绑定，因此当查询参数（bookmakers、过滤器）变化时会随之改变。直播和即将开始的赛事不会发出 ETag，因为它们的赔率历史仍在增长；对这些赛事的条件请求将作为带完整响应体的普通 200 响应。