GET historical-odds

Endpoint

GET /v4/historical-odds

Parametri della richiesta

• fixtureId* (string) — ID dell’incontro per il quale recuperare le quote storiche.
• bookmakers* (string) — Elenco di slugs di bookmaker separati da virgola (max 3) per filtrare i risultati. Esempio: pinnacle,bet365
• id (number) — (Opzionale) L’ID univoco di una specifica voce di quote storiche su cui filtrare.
• playerId (number) — (Opzionale) Il playerId associato alle quote per restringere i risultati.
• outcomeId (number) — (Opzionale) L’outcomeId per filtrare le quote relative a uno specifico esito.
• active (boolean) — (Opzionale) Filtra in base al fatto che la voce di quote sia attualmente attiva.

Header della richiesta

• If-None-Match (string) — (Facoltativo) Rinvia l'ETag di una risposta precedente per effettuare una richiesta condizionale. Se la risposta sarebbe identica, il server restituisce 304 Not Modified con corpo vuoto invece di reinviare il payload. Efficace solo per le fixture concluse o annullate (vedi «Richieste condizionali» di seguito).

Esempio di richiesta

GET /v4/historical-odds?fixtureId=id1000000758265379

Esempio di risposta

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

Risposta (200 OK)

In caso di richiesta andata a buon fine, il server risponde con un codice di stato 200 e restituisce una mappa da fixtureId a storici di quote annidati per bookmaker..

• bookmakers (object) — Quote raggruppate per slug del bookmaker
  • markets (object) — Ogni incontro contiene oggetti mercato con i relativi esiti.
  • outcomes (object) — ID esito con dati relativi ai giocatori.
  • players (object) — Giocatori con dati di quote contenenti:
    • id (number) — L’identificatore univoco della voce di quote storiche.
    • createdAt (string) — Il timestamp di creazione della voce di quote storiche.
    • price (number) — Il prezzo (quota) offerto.
    • limit (number) — La puntata massima consentita per quella quota.
    • active (boolean) — Indica se la quota è attualmente attiva.
    • exchangeMeta (object|null) — Metadati dell’exchange, se applicabile, inclusi prezzi back e lay.

Header della risposta (solo fixture concluse/annullate)

• ETag — Una breve stringa opaca che identifica il corpo della risposta corrente. Esempio: "a1b2c3d4e5f6a7b8".
• Cache-Control — private, max-age=259200 (3 giorni).

Risposta (304 Not Modified)

Viene restituito quando la richiesta include un header If-None-Match il cui valore corrisponde all'ETag corrente per questa fixture e combinazione di filtri. La risposta ha corpo vuoto; il client deve riutilizzare il payload precedentemente memorizzato in cache.

Richieste condizionali

Per le fixture concluse o annullate la risposta è deterministica, quindi ogni risposta 200 include un header ETag. I client che interrogano ripetutamente la stessa fixture possono memorizzare il corpo in cache localmente, poi inviare If-None-Match: <etag> nelle richieste successive per evitare di ritrasferire e rianalizzare un payload invariato:

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"

L'ETag è legato alla risposta esatta, quindi cambia quando cambiano i parametri della query (bookmaker, filtri). Le fixture live e in arrivo non emettono un ETag perché il loro storico quote è ancora in crescita; le richieste condizionali su tali fixture vengono servite come un normale 200 con il corpo completo.