Documentazione API: Integra i dati calcistici

Panoramica

Quali dati?

Statistiche dettagliate per giocatore e per squadra, indici di rendimento per ruolo, punti di forza e debolezze, valori di mercato stimati, proiezioni tra campionati, profili simili e punteggi di compatibilità giocatore-club.

Quale copertura?

Oltre 100 campionati maschili e femminili in Europa, Americhe, Asia e Africa, dai Big 5 alle divisioni inferiori e ai campionati giovanili, oltre alle coppe europee (Champions League, Europa League, Conference League). L'endpoint /v1/leagues restituisce i campionati accessibili con la tua chiave.

Quanto sono aggiornati i dati?

I dati vengono aggiornati ogni settimana, man mano che si giocano le giornate di campionato.

Come funziona l'accesso?

Abbonamento mensile per campionato: ogni abbonamento copre tutti i giocatori e le squadre del campionato scelto, con tutte le loro statistiche, coppe europee incluse. Tariffe su richiesta.

Domande frequenti

Le statistiche coprono la Champions League o le nazionali?

Le coppe europee (Champions League, Europa League, Conference League) sono incluse in qualsiasi abbonamento API senza costi aggiuntivi: i giocatori che vi partecipano hanno statistiche separate da quelle del campionato. Le statistiche con le nazionali, invece, non sono disponibili.

Con quale frequenza vengono aggiornati i dati?

Ogni settimana. Le statistiche includono le ultime giornate disputate di ogni campionato coperto.

Come ottengo una chiave API e le tariffe?

L'accesso all'API è disponibile su richiesta. Contattaci indicando i campionati che ti interessano: ti comunicheremo le tariffe e attiveremo la tua chiave.

Avvio rapido

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

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

Autenticazione

Tutte le richieste devono includere la tua chiave API nell'header HTTP X-API-Key.

X-API-Key: dk_live_a1b2c3d4e5f6...

Buone pratiche :

Non fare mai il commit di una chiave in un repository Git
Usa una chiave per ogni ambiente (prod, staging, dev)
Revoca immediatamente qualsiasi chiave compromessa
Imposta una data di scadenza per le chiavi temporanee

Identificatori dei giocatori

Nell'API coesistono due identificatori giocatore: sappiate quale memorizzare.

player_id : identifica una RIGA giocatore × contesto (stagione, club, competizione). Cambia ogni stagione, a ogni trasferimento e tra campionato e coppa europea: non memorizzarlo come chiave permanente.
datascout_id : identifica una PERSONA (formato ds_ + 16 caratteri): stabile tra stagioni, trasferimenti e competizioni. È la chiave consigliata per indicizzare i vostri dati.
datascout_id è presente in tutte le risposte giocatore (null se la riga non è ancora collegata, transitorio).
È accettato ovunque sia atteso un player_id (route /v1/players/:id/*, player_ids di /v1/compare e /v1/fit-score).
Per avviare il vostro referenziale: POST /v1/players/resolve-batch, poi memorizzate il datascout_id di ogni giocatore. GET /v1/players/:id/history restituisce la corrispondenza per stagione.

Limitazione delle richieste

Piano Pro Ligue: 10.000 richieste/giorno. Piano Pro Full: illimitato. Ogni risposta include i seguenti header:

X-RateLimit-Limit: limite giornaliero
X-RateLimit-Remaining: richieste rimanenti
X-RateLimit-Reset: data di reset (ISO 8601)

Codici di errore

Codice	Significato
200	Successo
400	Parametri mancanti o non validi
401	Chiave API mancante, non valida o scaduta
403	Piano insufficiente o campionato non accessibile
404	Risorsa non trovata
429	Rate limit superato
500	Errore del server

Endpoint

Profilo

Identità della chiave che chiama l'API

Riferimento

Metadati: campionati, stagioni, squadre

Giocatori

Ricerca, schede, statistiche, profili simili

Squadre

Scheda, rosa, similarità, confronto head-to-head

Allenatori

Ricerca, scheda, carriera e profilo tattico degli allenatori

Classifiche

Top giocatori per ruolo o per statistica

Glossario

Documentazione machine-readable delle statistiche e degli indici

Scouting

Ricerca avanzata multi-criterio

Le mie risorse

Indici e preset salvati nel tuo account DataScout

Confronto

Distribuzione di giocatori su 2 statistiche incrociate

Ruoli posizionali (27 profili)

Utilizzabili in /v1/rankings / /v1/scouting tramite il parametro role.

Portieri

gardien_stoppeur
gardien_moderne

Difensori centrali

defenseur_stoppeur
defenseur_relanceur
defenseur_moderne
defenseur_athletique

Terzini

arriere_lateral
lateral_offensif
lateral_interieur

Mediani

milieu_sentinelle
milieu_recuperateur
meneur_de_jeu_en_retrait

Centrocampisti centrali

milieu_box_to_box
mezzala
milieu_relayeur
milieu_ratisseur

Trequartisti

meneur_de_jeu
meneur_de_jeu_excentre

Ali

ailier_defensif
ailier_interieur
ailier_de_profondeur
ailier_provocateur
ailier_buteur

Attaccanti

faux_9
attaquant_pivot
attaquant_de_pressing
attaquant_de_profondeur
renard_des_surfaces
attaquant_complet

Esempi di codice

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_...')
}

Documentazione API