API Foresportia pour développeurs

SDK Python officiel

L’API Foresportia dispose maintenant d’un SDK Python officiel disponible sur PyPI. Il permet d’appeler les endpoints bêta depuis un script, un notebook ou un backend sans écrire manuellement les requêtes HTTP. L’accès API reste soumis à validation bêta privée : installer le package ne donne pas automatiquement accès aux données.

Développeur python ? Utilisez la doc officielle

pip install foresportia

from foresportia import ForesportiaClient

with ForesportiaClient.from_env() as client:
    picks = client.picks_today()

print(len(picks.get("matches", [])))

Le SDK lit `FORES_API_KEY` depuis l’environnement et l’envoie via l’en-tête `X-API-Key`. Liens : package PyPI · dépôt GitHub.

Conçue pour l’analyse, pas pour le conseil de pari

L’API est destinée à l’analytics sportif, aux dashboards, outils privés, bots, travaux de recherche et backtesting.

Ce n’est pas un conseil de pari et cela ne garantit aucun résultat. Les paris automatisés, la revente des données brutes ou la republication publique ne sont pas autorisés sans permission explicite.

Ce que fournit l’API

La bêta privée expose un schéma externe stable, séparé des endpoints utilisés par le site.

Probabilités 1X2

Probabilités domicile, nul et extérieur au format 0..1.

Badges de confiance

Badges machine et labels lisibles pour la stabilité du match.

Scores probables

Candidats de scores structurés quand la donnée est disponible.

BTTS / Over / Under

Marchés de buts exposés avec des champs propres.

Signaux de contexte

Classements, disponibilité et indicateurs contextuels quand ils sont assez fiables pour être exposés.

Données par ligue

Flux courts par ligue, match et date selon le périmètre disponible en beta.

Cas d’usage

L’API vise les intégrations football sérieuses qui ont besoin de données structurées, pas de promesses de résultat.

Dashboards football

Suivre les probabilités, les marchés de buts et les badges de stabilité.

Bots Telegram / Discord

Publier des lectures de matchs ou des alertes privées sur vos critères.

Notebooks Python

Explorer les signaux Foresportia avec pandas, notebooks ou scripts de recherche.

Previews de matchs

Enrichir une analyse éditoriale avec probabilités, contexte et tendances de buts.

Outils média / data analysis

Comparer les ligues, filtrer les matchs et préparer des formats de contenu data.

Endpoints bêta actuels

Chaque endpoint ci-dessous contient une description courte, le mode d’authentification, un exemple curl statique et un exemple compact de réponse. Les exemples protégés utilisent `YOUR_API_KEY` comme placeholder.

GET /v1/healthPublic

Vérifie publiquement l’état de la couche API v1.

curl

curl https://api.foresportia.com/v1/health

Exemple de réponse

{
  "status": "ok",
  "api_version": "v1",
  "source": "Foresportia"
}

Utilisez cet endpoint pour vérifier que la couche API publique est joignable.

GET /v1/meX-API-Key required

Retourne le statut du compte, le plan, les informations client et les endpoints disponibles pour la clé API courante.

curl

curl -H "X-API-Key: YOUR_API_KEY" \
  https://api.foresportia.com/v1/me

Exemple de réponse

{
  "status": "active",
  "plan": "beta_free",
  "client": {
    "name": "Example User",
    "email": "user@example.com",
    "usage_type": "dashboard"
  },
  "endpoints": [
    "GET /v1/health",
    "GET /v1/me",
    "GET /v1/me/usage",
    "GET /v1/leagues",
    "GET /v1/leagues/{league_code}/matches",
    "GET /v1/picks/today",
    "GET /v1/matches/today"
  ]
}

Cet endpoint permet d’identifier le compte bêta associé à la clé API utilisée côté serveur ou outil privé.

GET /v1/me/usageX-API-Key required

Retourne l’usage quotidien, mensuel et minute de la clé API courante.

curl

curl -H "X-API-Key: YOUR_API_KEY" \
  https://api.foresportia.com/v1/me/usage

Exemple de réponse

{
  "daily": {
    "date": "2026-05-20",
    "used": 17,
    "limit": 100,
    "remaining": 83
  },
  "monthly": {
    "month": "2026-05",
    "used": 177,
    "limit": 2000,
    "remaining": 1823
  },
  "rate_limit_minute": {
    "used": 2,
    "limit": 10,
    "remaining": 8
  },
  "last_used_at": "2026-05-20T09:20:25Z"
}

Les lignes retournées sont aussi suivies en interne pour le monitoring opérationnel.

GET /v1/picks/todayX-API-Key required

Retourne les picks sélectionnés pour la journée en cours. Il s’agit d’un sous-ensemble édité, pas de tous les matchs disponibles.

curl

curl -H "X-API-Key: YOUR_API_KEY" \
  https://api.foresportia.com/v1/picks/today

Exemple de réponse

{
  "date": "2026-05-20",
  "timezone": "Europe/Paris",
  "source": "Foresportia",
  "data_version": "example",
  "matches": [
    {
      "id": "0f5f178951689210",
      "kickoff": "2026-05-20T18:00:00Z",
      "kickoff_local": "2026-05-20T20:00:00+02:00",
      "league": {
        "code": "NOR",
        "name": "Eliteserien",
        "country": "Norway"
      },
      "home_team": "IK Start",
      "away_team": "FK Bodø/Glimt",
      "probabilities": {
        "home": 0.0844,
        "draw": 0.1712,
        "away": 0.7445
      },
      "confidence": {
        "badge": "ultra_stable",
        "label": "Very stable",
        "score": 0.773469
      },
      "likely_scores": [
        {
          "score": "1-1",
          "probability": 0.1234
        },
        {
          "score": "0-1",
          "probability": 0.1033
        }
      ],
      "markets": {
        "btts": 0.5539,
        "over_2_5": 0.6685,
        "under_2_5": 0.3315
      },
      "status": "scheduled",
      "pick": {
        "outcome": "away",
        "probability": 0.7445
      }
    }
  ]
}

Les probabilités et marchés sont au format ratio 0..1.

GET /v1/matches/todayX-API-Key required

Retourne tous les matchs disponibles aujourd’hui au format externe v1. L’objet match est similaire à `/v1/picks/today`, mais l’endpoint n’est pas limité aux picks sélectionnés.

curl

curl -H "X-API-Key: YOUR_API_KEY" \
  https://api.foresportia.com/v1/matches/today

Exemple de réponse

{
  "date": "2026-05-20",
  "timezone": "Europe/Paris",
  "source": "Foresportia",
  "data_version": "example",
  "matches": [
    {
      "id": "43636da1c3e70181",
      "kickoff": "2026-05-20T13:35:00Z",
      "kickoff_local": "2026-05-20T15:35:00+02:00",
      "league": {
        "code": "CHN",
        "name": "Chinese Super League",
        "country": "China"
      },
      "home_team": "Shanghai Shenhua",
      "away_team": "Wuhan Three Towns",
      "probabilities": {
        "home": 0.6624,
        "draw": 0.2206,
        "away": 0.117
      },
      "confidence": {
        "badge": "correct",
        "label": "Correct",
        "score": 0.73624
      },
      "markets": {
        "btts": 0.5425,
        "over_2_5": 0.5955,
        "under_2_5": 0.4045
      },
      "status": "scheduled",
      "pick": {
        "outcome": "home",
        "probability": 0.6624
      }
    }
  ]
}

Utilisez cet endpoint si vous avez besoin du flux quotidien complet plutôt que seulement des picks.

GET /v1/leaguesX-API-Key required

Retourne les codes de ligues disponibles et leurs métadonnées pour les flux enrichis court terme.

curl

curl -H "X-API-Key: YOUR_API_KEY" \
  https://api.foresportia.com/v1/leagues

Exemple de réponse

{
  "source": "Foresportia",
  "data_version": "example",
  "leagues": [
    {
      "code": "CHN",
      "name": "Chinese Super League",
      "country": "China",
      "available": true,
      "matches_available": 24
    },
    {
      "code": "NOR",
      "name": "Eliteserien",
      "country": "Norway",
      "available": true,
      "matches_available": 8
    }
  ]
}

Utilisez ces codes dans `/v1/leagues/{league_code}/matches`.

GET /v1/leagues/{league_code}/matchesX-API-Key required

Retourne un flux court borné par ligue. Cet endpoint supporte les fenêtres futures, passées récentes ou mixtes.

curl

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.foresportia.com/v1/leagues/CHN/matches?include=all&days=14&limit=20"

Exemple de réponse

{
  "league": {
    "code": "CHN",
    "name": "Chinese Super League",
    "country": "China"
  },
  "date_range": {
    "start": "2026-05-20",
    "end": "2026-06-02",
    "include": "all"
  },
  "timezone": "Europe/Paris",
  "source": "Foresportia",
  "data_version": "example",
  "matches": [
    {
      "id": "43636da1c3e70181",
      "kickoff": "2026-05-20T13:35:00Z",
      "kickoff_local": "2026-05-20T15:35:00+02:00",
      "league": {
        "code": "CHN",
        "name": "Chinese Super League",
        "country": "China"
      },
      "home_team": "Shanghai Shenhua",
      "away_team": "Wuhan Three Towns",
      "probabilities": {
        "home": 0.6624,
        "draw": 0.2206,
        "away": 0.117
      },
      "confidence": {
        "badge": "correct",
        "label": "Correct",
        "score": 0.73624
      },
      "markets": {
        "btts": 0.5425,
        "over_1_5": 0.9352,
        "over_2_5": 0.5955,
        "over_3_5": 0.6444,
        "under_1_5": 0.0648,
        "under_2_5": 0.4045,
        "under_3_5": 0.3556,
        "dnb_home": 0.8499,
        "dnb_away": 0.1501,
        "double_chance_1x": 0.883,
        "double_chance_x2": 0.3376,
        "double_chance_12": 0.7794
      },
      "ranking": {
        "home_rank": 9,
        "away_rank": 15,
        "home_context_rank": 3,
        "away_context_rank": 14,
        "source": "api_standings",
        "is_reliable": true
      },
      "status": "scheduled",
      "pick": {
        "outcome": "home",
        "probability": 0.6624
      }
    }
  ]
}

Ce n’est pas un export historique complet. Les matchs passés ici sont limités aux lignes récentes présentes dans les fichiers enrichis par ligue.

Champs communs de réponse

probabilities.home/draw/away	Probabilités 1X2 au format ratio 0..1.
markets.*	Probabilités des marchés au format ratio 0..1.
kickoff	Date/heure ISO-8601 en UTC.
kickoff_local	Date/heure convertie dans la timezone API, actuellement Europe/Paris.
confidence.badge	Valeur machine : `ultra_stable`, `stable`, `correct` ou `risk`.
confidence.label	Label lisible comme `Very stable`, `Stable`, `Correct` ou `Risk`.
pick.outcome	Prédiction 1X2 : `home`, `draw` ou `away`.
likely_scores.probability	Probabilité estimée du score exact quand elle est disponible.
ranking	Inclus seulement quand la donnée de classement est disponible et assez fiable pour être exposée.

Paramètres des matchs par ligue

include	`upcoming`, `past` ou `all`. Défaut : `upcoming`.
start	Date de début optionnelle au format `YYYY-MM-DD`.
days	Taille de fenêtre depuis `start`, entre 1 et 31 jours.
limit	Nombre maximum de lignes retournées, entre 1 et 500.

`upcoming` retourne uniquement les matchs à venir. `past` retourne les matchs passés récents disponibles dans les fichiers enrichis court terme. `all` retourne les matchs passés et futurs dans la fenêtre sélectionnée. Ce n’est pas un export historique complet.

Format des données

Probabilités

Les probabilités sont au format 0..1. Exemple : `0.7445` signifie `74,45 %`.

Horaires

`kickoff` est en UTC. `kickoff_local` est converti dans la timezone API, actuellement Europe/Paris.

Badges

`ultra_stable`, `stable`, `correct`, `risk` sont les valeurs machine.

Labels

`Very stable`, `Stable`, `Correct`, `Risk` sont fournis dans `confidence.label`.

Authentification et limites

Utilisez l’en-tête `X-API-Key`. Les clés API sont privées et ne doivent pas être exposées dans du code frontend public ou des dépôts GitHub. Appelez l’API depuis un backend, script, bot ou environnement privé.

curl -H "X-API-Key: YOUR_API_KEY" \
  https://api.foresportia.com/v1/picks/today

beta_free

100 requêtes/jour, 2000 requêtes/mois, 10 requêtes/minute.

Limites évolutives

Les quotas de bêta privée peuvent évoluer selon les usages observés.

Lignes suivies

Les lignes retournées sont aussi suivies en interne.

Gestion des erreurs

Tous les endpoints renvoient des codes HTTP standards. Les erreurs sont retournées en JSON avec un champ message court.

200 OK	Requête traitée avec succès.
400 Bad Request	Paramètre invalide (par ex. `league_code` inconnu, `days`/`limit` hors limites).
401 Unauthorized	En-tête `X-API-Key` manquant ou invalide.
403 Forbidden	Clé non autorisée pour cet endpoint ou accès bêta non encore activé.
404 Not Found	Ressource introuvable (par ex. code de ligue inconnu).
429 Too Many Requests	Limite par minute, journalière ou mensuelle dépassée. Réessayer après la fenêtre.
5xx Server Error	Erreur backend temporaire. Réessayer avec un backoff exponentiel.

Les codes 5xx sont à traiter comme transitoires côté client, pas comme des erreurs définitives.

Prompt à copier dans ChatGPT, Claude ou une autre IA

Utilisez ce prompt pour demander à une IA de vous aider à intégrer l’API. Si votre assistant IA a accès au web, il peut lire cette page. Ne collez votre vraie clé API que dans un environnement privé que vous acceptez d’utiliser avec l’outil IA ; sinon, gardez-la dans une variable d’environnement.

Tu es mon assistant technique. Aide-moi à utiliser l’API bêta privée Foresportia.

Lis d’abord la documentation publique :
https://www.foresportia.com/api.html

Objectif :
- appeler l’API Foresportia depuis un script ou un backend, pas depuis du JavaScript frontend public ;
- utiliser le header X-API-Key ;
- garder ma clé API dans une variable d’environnement nommée FORES_API_KEY ;
- ne jamais afficher, logger ou commiter la clé API ;
- récupérer les endpoints utiles selon mon besoin : /v1/me, /v1/me/usage, /v1/picks/today, /v1/matches/today, /v1/leagues, /v1/leagues/{league_code}/matches ;
- respecter les limites de la bêta et gérer les erreurs 401, 429 et erreurs réseau.

Contexte important :
- Les probabilités et marchés sont au format ratio 0..1.
- kickoff est en UTC et kickoff_local est dans la timezone API.
- Foresportia fournit des données d’analyse football et des probabilités de modèle. Ce n’est pas un conseil de pari et il n’y a aucune garantie de résultat.

Commence par me proposer une implémentation simple et sûre dans le langage suivant : [Python / Node.js / autre].
Utilise YOUR_API_KEY uniquement comme placeholder dans les exemples.

Conseil : remplacez uniquement le langage souhaité. Pour un usage réel, stockez la clé dans `FORES_API_KEY` côté serveur ou local privé.

Dashboard API connecté

La gestion de l’usage, des clés actives et de la rotation est maintenant séparée de cette documentation publique.

Déjà accès à l’API ? Ouvrir le dashboard API

Connexion sans mot de passe par email et code temporaire. Les clés existantes ne sont jamais affichées en clair.

Ouvrir le dashboard API

Demander un accès bêta

Le formulaire bêta existant est disponible sur la page d’intérêt API. Les demandes sont relues manuellement. Vous pouvez aussi écrire à contact@foresportia.com avec un court descriptif de votre projet.

Demander un accès bêta Aucun nouvel endpoint backend de formulaire n’est ajouté sur cette page.