GET historical-odds

Endpoint

GET /v4/historical-odds

Paramètres de requête

• fixtureId* (string) — ID du match pour lequel récupérer les cotes historiques.
• bookmakers* (string) — Liste de slugs de bookmakers séparés par des virgules (max 3) pour filtrer les résultats. Exemple : pinnacle,bet365
• id (number) — (Optionnel) ID unique d’une entrée de cotes historiques spécifique pour filtrer les résultats.
• playerId (number) — (Optionnel) playerId associé aux cotes pour restreindre les résultats.
• outcomeId (number) — (Optionnel) outcomeId pour filtrer les cotes d’une issue spécifique.
• active (boolean) — (Optionnel) Filtrer selon que l’entrée de cotes est actuellement active ou non.

En-têtes de requête

• If-None-Match (string) — (Facultatif) Renvoyez l'ETag d'une réponse précédente pour effectuer une requête conditionnelle. Si la réponse serait identique, le serveur retourne 304 Not Modified avec un corps vide au lieu de renvoyer la charge utile. Uniquement effectif pour les fixtures terminées ou annulées (voir « Requêtes conditionnelles » ci-dessous).

Exemple de requête

GET /v4/historical-odds?fixtureId=id1000000758265379

Exemple de réponse

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

Réponse (200 OK)

En cas de requête réussie, le serveur répond avec un code de statut 200 et renvoie une map de fixtureId vers un historique de cotes imbriqué par bookmaker..

• bookmakers (object) — Cotes regroupées par slug de bookmaker
  • markets (object) — Chaque match contient des objets de marché avec leurs issues.
  • outcomes (object) — IDs d’issue avec données de joueurs.
  • players (object) — Joueurs avec des données de cotes comprenant:
    • id (number) — Identifiant unique de l’entrée de cotes historiques.
    • createdAt (string) — Horodatage de la création de l’entrée de cotes historiques.
    • price (number) — Le prix (cotes) proposé.
    • limit (number) — La mise maximale autorisée pour ces cotes.
    • active (boolean) — Indique si les cotes sont actuellement actives.
    • exchangeMeta (object|null) — Métadonnées d’exchange le cas échéant, incluant les prix back et lay.

En-têtes de réponse (uniquement pour les fixtures terminées/annulées)

• ETag — Une courte chaîne opaque identifiant le corps de la réponse actuelle. Exemple : "a1b2c3d4e5f6a7b8".
• Cache-Control — private, max-age=259200 (3 jours).

Réponse (304 Not Modified)

Retourné lorsque la requête inclut un en-tête If-None-Match dont la valeur correspond à l'ETag actuel pour cette fixture et cette combinaison de filtres. La réponse a un corps vide ; le client doit réutiliser sa charge utile précédemment mise en cache.

Requêtes conditionnelles

Pour les fixtures terminées ou annulées, la réponse est déterministe, donc chaque réponse 200 inclut un en-tête ETag. Les clients qui interrogent la même fixture à plusieurs reprises peuvent mettre le corps en cache localement, puis envoyer If-None-Match: <etag> sur les requêtes suivantes pour éviter de retransférer et de réanalyser une charge utile inchangée :

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 est lié à la réponse exacte ; il change donc lorsque les paramètres de requête (bookmakers, filtres) changent. Les fixtures en direct et à venir n'émettent pas d'ETag car leur historique de cotes continue de s'enrichir ; les requêtes conditionnelles sur ces fixtures sont servies comme un 200 normal avec le corps complet.