Utilisation d'une API

Dans : Chroniques

ESPN Hidden API : Principes & Utilisation dans ToddBet

Cet article explique le principe de l'API ESPN utilisée clandestinement par le module todd_bet pour récupérer les données sportives en temps réel et les logos officiels des équipes.

Nature de l'API et son aspect "Hidden"

Contrairement à de nombreuses plateformes qui vendent l'accès à leurs données sportives à prix d'or (comme Sportradar ou Opta), le géant média américain ESPN dispose d'une infrastructure API colossale qui propulse son propre site Web officiel et ses applications mobiles.

Cette API est qualifiée de "Hidden" (Cachée) ou "Non-officiée" car :

  • Elle n'est nulle part documentée officiellement par ESPN à l'intention des développeurs tiers.
  • Elle n'exige aucune clé d'API, aucun token OAuth ni aucune authentification.
  • Elle est totalement ouverte et joignable via de simples requêtes HTTP GET.

C'est une mine d'or découverte par la communauté des développeurs open-source par rétro-ingénierie (en inspectant simplement le trafic réseau du site officiel d'ESPN).

Le type de données accessibles

Sa puissance réside dans sa richesse inouïe. L'API (souvent sous le domaine site.api.espn.com/apis/site/v2/...) centralise le monde du sport. Elle donne un accès brut (au format JSON) à :

  • Le calendrier structuré (Scoreboard) de dizaines de sports (Football, Basket, Baseball, Hockey, etc.) et centaines de ligues (Ligue 1, NBA, NFL, Champions League...).
  • Les statuts en direct (Live State) : des indicateurs exacts pour savoir si le match est "à venir" (pre), "en cours" (in), ou "terminé" (post).
  • L'horloge temps-réel (ex: "74' - 2ème Mi-Temps" ou "Fin du 3ème Quart-temps").
  • Les Médias : Les URL vers les logos officiels des équipes de très haute qualité (souvent au format PNG avec transparence native), ainsi que les teintes hexadécimales primaires et secondaires des clubs (pratique pour l'UI).
  • Les statistiques détaillées (Possession, Tirs balistiques, Fautes) ainsi que les compositions d'équipe / blessures.

Technique pour l'interroger

La technique d'interrogation repose sur de simples requêtes HTTPS GET vers des endpoints déduits paramétriquement.

Exemple 1 : Obtenir le calendrier (Scoreboard)

http://site.api.espn.com/apis/site/v2/sports/{sport}/{league}/scoreboard?dates=YYYYMMDD-YYYYMMDD&limit=50

Ici on demande les 50 prochains matchs pour un sport et une ligue donnée, avec la fourchette de date souhaitée.

Exemple 2 : Obtenir le détail pointu d'un match (Summary)

http://site.api.espn.com/apis/site/v2/sports/{sport}/{league}/summary?event={ID_DU_MATCH}

⚠️ Précautions Techniques et CORS

Parce qu'elle n'est pas prévue pour du partage inter-domaines public, l'API d'ESPN bloque souvent les requêtes front-end directes (Javascript natif type fetch() depuis un navigateur) via la politique CORS (Cross-Origin Resource Sharing).

La technique absolue consiste donc à effectuer un proxy côté serveur (Server-Side) : C'est le serveur PHP de votre application (via cURL) qui discute avec ESPN et qui relaye l'information nettoyée à votre client Front-End.

Stratégie d'utilisation dans TODD (ToddBet)

Dans le module todd_bet, nous exploitons l'API cachée via le gestionnaire asynchrone (plugins/todd/modules/todd_bet/handler.php). Ce "Proxy PHP" se charge de masquer l'origine de nos requêtes à ESPN.

Le processus se divise en deux usages majeurs :

La Modale d'Import (Admin)

Au lieu que l'administrateur doive créer péniblement un pari sportif en cherchant les URL de logos sur Google, il utilise l'interface magique :

  1. L'admin clique sur une compétition (ex: "Ligue 1").
  2. Notre handler.php exécute un cURL vers l'endpoint Scoreboard d'ESPN avec une pondération de date (Aujourd'hui + 10 jours dans le futur).
  3. Le serveur décode l'énorme bloc JSON, extrait uniquement l'essentiel (Nom des équipes, Logos propres, ID du match) et le renvoie au front admin.
  4. Au clic sur le match souhaité, ToddBet sauvegarde durablement en base MMI l'identifiant ESPN unique du match.

Le Live Scoring (Public)

Une application sur un écran public de salle de repos va être consultée simultanément, et la page va tourner pendant des heures. Si l'écran actualisait la page ESPN toutes les 5 secondes via le client, on se ferait bannir l'adresse IP immédiatemment.

  1. Le fichier javascript public (client.js) interroge notre serveur TODD locales toutes les 8 ou 10 secondes en lui fournissant l'ID ESPN du dit-pari.
  2. Notre handler.php ne contacte pas ESPN à chaque fois ! Il implémente un micro-cache fichier sécurisé (todd_espn_live_xxx.json).
  3. Si le cache a plus de 45 secondes d'existence (TTL), le PHP lance un cURL vers l'endpoint Summary d'ESPN, extrait le temps, le score direct, et ré-écrit le cache.
  4. En dessous de ce seuil de 45 secondes, notre serveur sert simplement le fichier statique mis en cache, soulageant ainsi nos infrastructures réseau mutuelles et s'assurant une résilience totale et transparente face aux limites de débit (Rate-Limiting) d'ESPN.