GET historical-odds

Endpoint

GET /v4/historical-odds

Parâmetros da requisição

• fixtureId* (string) — ID da partida para a qual recuperar odds históricas.
• bookmakers* (string) — Lista de slugs de bookmakers separados por vírgula (máx. 3) para filtrar resultados. Exemplo: pinnacle,bet365
• id (number) — (Opcional) O ID único de um registro específico de odds históricas para filtrar.
• playerId (number) — (Opcional) O playerId associado às odds para refinar os resultados.
• outcomeId (number) — (Opcional) O outcomeId para filtrar as odds de um outcome específico.
• active (boolean) — (Opcional) Filtrar com base em se o registro de odds está atualmente ativo.

Cabeçalhos da requisição

• If-None-Match (string) — (Opcional) Retorne o ETag de uma resposta anterior para fazer uma requisição condicional. Se a resposta for idêntica, o servidor retorna 304 Not Modified com corpo vazio em vez de reenviar o payload. Efetivo apenas para fixtures finalizadas ou canceladas (veja "Requisições condicionais" abaixo).

Exemplo de requisição

GET /v4/historical-odds?fixtureId=id1000000758265379

Exemplo de resposta

{
  "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
                  }
                ]
              }
            }
          }
        }
      }
    }
  }
}

Resposta (200 OK)

Em uma requisição bem-sucedida, o servidor responde com um código de status 200 e retorna um mapa de fixtureId para históricos de odds aninhados por bookmaker..

• bookmakers (object) — Odds agrupadas por slug do bookmaker
  • markets (object) — Cada partida contém objetos de mercado com outcomes.
  • outcomes (object) — IDs de outcome com dados de jogadores.
  • players (object) — Jogadores com dados de odds contendo:
    • id (number) — O identificador único do registro de odds históricas.
    • createdAt (string) — O timestamp em que o registro de odds históricas foi criado.
    • price (number) — O preço (odd) oferecido.
    • limit (number) — A aposta máxima permitida para essa odd.
    • active (boolean) — Indica se a odd está ativa no momento.
    • exchangeMeta (object|null) — Metadados de exchange, se aplicável, incluindo preços back e lay.

Cabeçalhos da resposta (apenas fixtures finalizadas/canceladas)

• ETag — Uma pequena string opaca que identifica o corpo atual da resposta. Exemplo: "a1b2c3d4e5f6a7b8".
• Cache-Control — private, max-age=259200 (3 dias).

Resposta (304 Not Modified)

Retornado quando a requisição inclui um cabeçalho If-None-Match cujo valor corresponde ao ETag atual desta fixture e combinação de filtros. A resposta tem corpo vazio; o cliente deve reutilizar o payload anteriormente armazenado em cache.

Requisições condicionais

Para fixtures finalizadas ou canceladas a resposta é determinística, então toda resposta 200 inclui um cabeçalho ETag. Clientes que fazem polling da mesma fixture repetidamente podem armazenar o corpo em cache localmente e enviar If-None-Match: <etag> nas requisições seguintes para evitar retransferir e reanalisar um payload que não mudou:

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"

O ETag está vinculado à resposta exata, portanto ele muda quando os parâmetros da consulta (bookmakers, filtros) mudam. Fixtures ao vivo e futuras não emitem ETag porque seu histórico de odds ainda está crescendo; requisições condicionais nessas fixtures são servidas como um 200 normal com o corpo completo.