API-documentatie: Integreer voetbaldata

Overzicht

Welke data?

Gedetailleerde speler- en teamstatistieken, prestatie-indices per rol, sterktes en zwaktes, geschatte marktwaardes, projecties tussen competities, vergelijkbare spelersprofielen en speler-club fit-scores.

Welke dekking?

Meer dan 100 mannen- en vrouwencompetities in Europa, Amerika, Azië en Afrika, van de Big 5 tot lagere divisies en jeugdcompetities, plus de Europese bekers (Champions League, Europa League, Conference League). Het endpoint /v1/leagues geeft de competities terug die met jouw sleutel toegankelijk zijn.

Hoe actueel is de data?

De data wordt elke week bijgewerkt, naarmate de speelrondes van de competities worden gespeeld.

Hoe werkt de toegang?

Maandabonnement per competitie: elk abonnement dekt alle spelers en teams van de gekozen competitie, met al hun statistieken, Europese bekers inbegrepen. Tarieven op aanvraag.

Veelgestelde vragen

Dekken de statistieken de Champions League of nationale teams?

De Europese bekers (Champions League, Europa League, Conference League) zijn zonder meerkosten inbegrepen bij elk API-abonnement: spelers die eraan deelnemen hebben daar aparte statistieken, los van die van hun competitie. Statistieken bij nationale teams zijn daarentegen niet beschikbaar.

Hoe vaak wordt de data bijgewerkt?

Elke week. De statistieken bevatten de laatst gespeelde speelrondes van elke gedekte competitie.

Hoe krijg ik een API-sleutel en de tarieven?

API-toegang is beschikbaar op aanvraag. Neem contact met ons op en vermeld de competities die je interesseren: we delen de tarieven en activeren je sleutel.

Snel starten

Basis-URL : https://api.datascout.fr/v1

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

Authenticatie

Elke aanvraag moet je API-sleutel bevatten in de HTTP-header X-API-Key.

X-API-Key: dk_live_a1b2c3d4e5f6...

Beste praktijken :

Commit nooit een sleutel naar een Git-repository
Gebruik één sleutel per omgeving (productie, staging, ontwikkeling)
Trek een gecompromitteerde sleutel onmiddellijk in
Stel een vervaldatum in voor tijdelijke sleutels

Speler-identifiers

In de API bestaan twee speler-identifiers naast elkaar: weet welke u moet opslaan.

player_id : identificeert een RIJ speler × context (seizoen, club, competitie). Hij verandert elk seizoen, bij elke transfer en tussen competitie en Europees voetbal: sla hem niet op als duurzame sleutel.
datascout_id : identificeert een PERSOON (formaat ds_ + 16 tekens): stabiel over seizoenen, transfers en competities heen. Dit is de aanbevolen sleutel om uw gegevens te indexeren.
datascout_id is aanwezig in elk spelersantwoord (null als de rij nog niet gekoppeld is, tijdelijk).
Hij wordt overal geaccepteerd waar een player_id wordt verwacht (/v1/players/:id/*-routes, player_ids in /v1/compare en /v1/fit-score).
Om uw referentieel op te starten: POST /v1/players/resolve-batch en sla de datascout_id van elke speler op. GET /v1/players/:id/history geeft de koppeling per seizoen.

Rate limiting

Plan Pro Ligue: 10.000 aanvragen/dag. Plan Pro Full: onbeperkt. Elke reactie bevat de volgende headers:

X-RateLimit-Limit: dagelijkse limiet
X-RateLimit-Remaining: resterende aanvragen
X-RateLimit-Reset: resetdatum (ISO 8601)

Foutcodes

Code	Betekenis
200	Succes
400	Ontbrekende of ongeldige parameters
401	Ontbrekende, ongeldige of verlopen API-sleutel
403	Onvoldoende plan of niet-toegankelijke competitie
404	Bron niet gevonden
429	Rate limit overschreden
500	Serverfout

Endpoints

Profiel

Identiteit van de sleutel die de API aanroept

Referentie

Metadata: competities, seizoenen, teams

Spelers

Zoeken, profielen, statistieken, vergelijkbare spelers

Teams

Profiel, selectie, gelijkenis, head-to-head-vergelijking

Trainers

Zoeken, profiel, carrière en tactisch profiel van trainers

Ranglijsten

Topspelers per rol of statistiek

Woordenlijst

Machineleesbare documentatie van statistieken en indices

Scouting

Geavanceerd zoeken met meerdere criteria

Mijn bronnen

Indexen en presets opgeslagen in je DataScout-account

Vergelijking

Spreiding van spelers over 2 gekruiste statistieken

Positionele rollen (27 profielen)

Te gebruiken in /v1/rankings / /v1/scouting via de parameter role.

Doelmannen

gardien_stoppeur
gardien_moderne

Centrale verdedigers

defenseur_stoppeur
defenseur_relanceur
defenseur_moderne
defenseur_athletique

Backs

arriere_lateral
lateral_offensif
lateral_interieur

Verdedigende middenvelders

milieu_sentinelle
milieu_recuperateur
meneur_de_jeu_en_retrait

Centrale middenvelders

milieu_box_to_box
mezzala
milieu_relayeur
milieu_ratisseur

Aanvallende middenvelders

meneur_de_jeu
meneur_de_jeu_excentre

Buitenspelers

ailier_defensif
ailier_interieur
ailier_de_profondeur
ailier_provocateur
ailier_buteur

Aanvallers

faux_9
attaquant_pivot
attaquant_de_pressing
attaquant_de_profondeur
renard_des_surfaces
attaquant_complet

Codevoorbeelden

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

API-documentatie