Documentation API : Intégrez les données football

Vue d'ensemble

Quelles données ?

Statistiques détaillées par joueur et par équipe, indices de performance par rôle, forces et faiblesses, valeurs marchandes estimées, projections inter-championnats, profils similaires et scores d'adéquation joueur-club.

Quelle couverture ?

Plus de 100 championnats masculins et féminins en Europe, Amériques, Asie et Afrique, du Big 5 aux divisions inférieures et championnats de jeunes, ainsi que les coupes d'Europe (Ligue des Champions, Europa League, Conference League). L'endpoint /v1/leagues renvoie la liste des championnats accessibles avec votre clé.

Quelle fraîcheur ?

Les données sont mises à jour chaque semaine, au fil des journées de championnat disputées.

Quel modèle d'accès ?

Abonnement mensuel par championnat : chaque abonnement couvre l'ensemble des joueurs et des équipes du championnat choisi, avec toutes leurs statistiques, coupes d'Europe incluses. Tarifs sur demande.

Questions fréquentes

Les statistiques couvrent-elles la Ligue des champions ou les équipes nationales ?

Les coupes d'Europe (Ligue des Champions, Europa League, Conference League) sont incluses avec tout abonnement API, sans surcoût : les joueurs qui y participent disposent de statistiques distinctes de celles de leur championnat. En revanche, les statistiques en équipe nationale ne sont pas disponibles.

À quelle fréquence les données sont-elles mises à jour ?

Chaque semaine. Les statistiques intègrent les dernières journées disputées de chaque championnat couvert.

Comment obtenir une clé API et connaître les tarifs ?

L'accès API est disponible sur demande. Contactez-nous en précisant les championnats qui vous intéressent : nous vous communiquerons les tarifs et activerons votre clé.

Démarrage rapide

URL de base : https://api.datascout.fr/v1

curl -H "X-API-Key: dk_live_YOUR_KEY" \
  https://api.datascout.fr/v1/leagues

Authentification

Toutes les requêtes doivent inclure votre clé API dans l'en-tête HTTP X-API-Key.

X-API-Key: dk_live_a1b2c3d4e5f6...

Bonnes pratiques :

Ne committez jamais une clé dans un dépôt Git
Utilisez une clé par environnement (prod, staging, dev)
Révoquez immédiatement toute clé compromise
Définissez une date d'expiration pour les clés temporaires

Identifiants joueurs

Deux identifiants joueur coexistent dans l'API : sachez lequel stocker.

player_id : identifie une LIGNE joueur × contexte (saison, club, compétition). Il change à chaque saison, à chaque transfert et entre championnat et coupe d'Europe : ne le stockez pas comme clé pérenne.
datascout_id : identifie une PERSONNE (format ds_ + 16 caractères) : stable entre saisons, transferts et compétitions. C'est la clé recommandée pour indexer vos données.
datascout_id est présent dans toutes les réponses joueur (null si la ligne n'est pas encore rattachée, transitoire).
Il est accepté partout où un player_id est attendu (routes /v1/players/:id/*, player_ids de /v1/compare et /v1/fit-score).
Pour amorcer votre référentiel : POST /v1/players/resolve-batch, puis stockez le datascout_id de chaque joueur. GET /v1/players/:id/history donne la correspondance par saison.

Limitation du débit

Plan Pro Ligue : 10 000 requêtes/jour. Plan Pro Full : illimité. Chaque réponse inclut les en-têtes suivants :

X-RateLimit-Limit: limite journalière
X-RateLimit-Remaining: requêtes restantes
X-RateLimit-Reset: date de reset (ISO 8601)

Codes d'erreur

Code	Signification
200	Succès
400	Paramètres manquants ou invalides
401	Clé API manquante, invalide ou expirée
403	Plan insuffisant ou ligue non accessible
404	Ressource introuvable
429	Rate limit dépassé
500	Erreur serveur

Endpoints

Profil

Identité de la clé qui appelle l'API

Référentiel

Métadonnées : ligues, saisons, équipes

Joueurs

Recherche, fiches, stats, profils similaires

Équipes

Fiche, effectif, similarité, comparaison head-to-head

Coachs

Recherche, fiche, carrière et profil tactique des entraîneurs

Classements

Top joueurs par rôle ou par statistique

Glossaire

Documentation machine-readable des stats et indices

Scouting

Recherche multi-critères avancée

Mes ressources

Indices et presets stockés dans votre compte DataScout

Comparaison

Distribution de joueurs sur 2 stats croisées

Rôles positionnels (31 profils)

Utilisables dans /v1/rankings / /v1/scouting via le paramètre role.

Six clés ont été renommées le 18 septembre 2026 pour coller aux libellés affichés. Les anciennes clés restent acceptées : GET /v1/enums donne l'ancienne clé de chaque rôle renommé dans son champ deprecated_key.

Gardiens

gardien_stoppeur
gardien_moderne
gardien_relanceur

Défenseurs centraux

defenseur_stoppeur
defenseur_relanceur
defenseur_mobile
defenseur_aerien

Latéraux

lateral_defensif
lateral_offensif
lateral_athletique
lateral_passeur

Milieux défensifs

milieu_progressif
milieu_recuperateur
meneur_de_jeu_en_retrait

Milieux centraux

milieu_box_to_box
mezzala
milieu_relayeur
milieu_ratisseur

Milieux offensifs

meneur_de_jeu
meneur_percuteur
meneur_travailleur
meneur_de_jeu_excentre

Ailiers

ailier_travailleur
ailier_de_profondeur
ailier_provocateur
ailier_buteur

Attaquants

faux_9
attaquant_pivot
attaquant_de_pressing
attaquant_de_profondeur
renard_des_surfaces

Valeurs recalculées

Le contrat de version porte sur la forme des réponses, pas sur les valeurs. Nos indicateurs (indice de performance, rôles, similarité, projection, valeur marchande estimée) sont recalculés chaque semaine et leurs méthodes évoluent. Ne figez pas de seuil numérique sur un score, rafraîchissez les valeurs que vous stockez, et utilisez datascout_id comme seule clé pérenne. Les évolutions qui déplacent des valeurs sont annoncées par email aux détenteurs de clés actives.

Exemples de code

Python

import requests

API_KEY = "dk_live_..."
headers = {"X-API-Key": API_KEY}

# Top 10 ailiers buteurs - France D1
r = requests.get(
    "https://api.datascout.fr/v1/rankings",
    params={
        "role": "ailier_buteur",
        "saison": "25-26",
        "league": "France D1",
        "limit": 10
    },
    headers=headers
)
print(r.json()["data"])

Node.js (axios)

const axios = require("axios")

const api = axios.create({
  baseURL: "https://api.datascout.fr/v1",
  headers: { "X-API-Key": process.env.DATASCOUT_API_KEY }
})

const { data } = await api.post("/scouting", {
  saison: "25-26",
  roles: ["ailier_buteur"],
  ageMax: 23,
  minutesMin: 1000,
  limit: 20
})

console.log(data.data)

R (httr2)

library(httr2)

API_KEY <- "dk_live_..."

# GET : top 10 ailiers buteurs en Ligue 1
resp <- request("https://api.datascout.fr/v1/rankings") |>
  req_url_query(role = "ailier_buteur", saison = "25-26",
                league = "France D1", limit = 10) |>
  req_headers("X-API-Key" = API_KEY) |>
  req_perform()

players <- resp |> resp_body_json() |> _$data

# Conversion en data.frame
df <- do.call(rbind, lapply(players, function(p) {
  data.frame(rank = p$rank, name = p$name, club = p$club,
             score = p$score, stringsAsFactors = FALSE)
}))

Google Sheets (Apps Script)

// Extensions → Apps Script. Copier ce code puis utiliser en cellule :
// =DATASCOUT_RANKING("ailier_buteur", "25-26", "France D1", 20)

function DATASCOUT_RANKING(role, saison, league, limit) {
  const key = PropertiesService.getScriptProperties()
    .getProperty('DATASCOUT_API_KEY')
  const url = 'https://api.datascout.fr/v1/rankings?' +
    'role=' + role + '&saison=' + saison +
    '&league=' + encodeURIComponent(league) +
    '&limit=' + (limit || 10)

  const resp = UrlFetchApp.fetch(url, {
    method: 'get',
    headers: { 'X-API-Key': key }
  })
  const data = JSON.parse(resp.getContentText())

  const rows = [['Rang', 'Joueur', 'Club', 'Âge', 'Note']]
  data.data.forEach(p => rows.push([p.rank, p.name, p.club, p.age, p.score]))
  return rows
}

// Une seule fois : stocker la clé en sécurité
function setupApiKey() {
  PropertiesService.getScriptProperties()
    .setProperty('DATASCOUT_API_KEY', 'dk_live_...')
}

Documentation API