GET historical-odds

Endpoint

GET /v4/historical-odds

Parámetros de la petición

• fixtureId* (string) — ID del partido para el que se quieren recuperar cuotas históricas.
• bookmakers* (string) — Lista de slugs de casas de apuestas separados por comas (máx. 3) para filtrar resultados. Ejemplo: pinnacle,bet365
• id (number) — (Opcional) El ID único de una entrada específica de cuotas históricas por la que filtrar.
• playerId (number) — (Opcional) El playerId asociado a las cuotas para acotar los resultados.
• outcomeId (number) — (Opcional) El outcomeId para filtrar las cuotas de un resultado específico.
• active (boolean) — (Opcional) Filtrar según si la entrada de cuotas está actualmente activa.

Cabeceras de la solicitud

• If-None-Match (string) — (Opcional) Reenvía el ETag de una respuesta anterior para hacer una solicitud condicional. Si la respuesta sería idéntica, el servidor devuelve 304 Not Modified con un cuerpo vacío en lugar de reenviar la carga útil. Solo es efectivo para fixtures finalizados o cancelados (ver «Solicitudes condicionales» más abajo).

Ejemplo de petición

GET /v4/historical-odds?fixtureId=id1000000758265379

Ejemplo de respuesta

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

Respuesta (200 OK)

En una petición exitosa, el servidor responde con el código de estado 200 y devuelve un mapa de fixtureId a historiales de cuotas anidadas por casa de apuestas..

• bookmakers (object) — Cuotas agrupadas por slug de la casa de apuestas
  • markets (object) — Cada partido contiene objetos de mercado con resultados.
  • outcomes (object) — IDs de resultado con datos de jugadores.
  • players (object) — Jugadores con datos de cuotas que contienen:
    • id (number) — El identificador único de la entrada de cuotas históricas.
    • createdAt (string) — La marca de tiempo en que se creó la entrada de cuotas históricas.
    • price (number) — El precio (cuotas) ofrecido.
    • limit (number) — La apuesta máxima permitida para esas cuotas.
    • active (boolean) — Indica si las cuotas están actualmente activas.
    • exchangeMeta (object|null) — Metadatos de exchange, si aplica, incluyendo precios back y lay.

Cabeceras de la respuesta (solo fixtures finalizados/cancelados)

• ETag — Una cadena opaca corta que identifica el cuerpo actual de la respuesta. Ejemplo: "a1b2c3d4e5f6a7b8".
• Cache-Control — private, max-age=259200 (3 días).

Respuesta (304 Not Modified)

Se devuelve cuando la solicitud incluye una cabecera If-None-Match cuyo valor coincide con el ETag actual de este fixture y combinación de filtros. La respuesta tiene un cuerpo vacío; el cliente debe reutilizar la carga útil que tenía en caché.

Solicitudes condicionales

Para los fixtures finalizados o cancelados la respuesta es determinista, por lo que cada respuesta 200 incluye una cabecera ETag. Los clientes que consultan repetidamente el mismo fixture pueden cachear el cuerpo localmente y enviar If-None-Match: <etag> en las solicitudes siguientes para evitar retransferir y volver a analizar una carga útil que no ha cambiado:

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"

El ETag está ligado a la respuesta exacta, por lo que cambia cuando cambian los parámetros de consulta (bookmakers, filtros). Los fixtures en directo y próximos no emiten ETag porque su historial de cuotas sigue creciendo; las solicitudes condicionales sobre esos fixtures se sirven como un 200 normal con el cuerpo completo.