REST-API v1

API-Dokumentation

Integriere die Daten von DataScout über unsere REST-API in deine eigenen Tools.

Überblick

Welche Daten?

Detaillierte Spieler- und Teamstatistiken, rollenbasierte Leistungsindizes, Stärken und Schwächen, geschätzte Marktwerte, ligaübergreifende Projektionen, ähnliche Spielerprofile und Spieler-Klub-Fit-Scores.

Welche Abdeckung?

Über 100 Männer- und Frauenligen in Europa, Amerika, Asien und Afrika – von den Big 5 bis zu unteren Ligen und Jugendligen, dazu die Europapokale (Champions League, Europa League, Conference League). Der Endpoint /v1/leagues liefert die mit deinem Schlüssel zugänglichen Ligen.

Wie aktuell sind die Daten?

Die Daten werden jede Woche aktualisiert, sobald die Spieltage der Ligen gespielt sind.

Wie funktioniert der Zugang?

Monatsabonnement pro Liga: Jedes Abonnement umfasst alle Spieler und Teams der gewählten Liga mit sämtlichen Statistiken, Europapokale inklusive. Preise auf Anfrage.

Häufige Fragen

Decken die Statistiken die Champions League oder Nationalmannschaften ab?

Die Europapokale (Champions League, Europa League, Conference League) sind in jedem API-Abonnement ohne Aufpreis enthalten: Spieler, die daran teilnehmen, haben dort eigene, von der Liga getrennte Statistiken. Statistiken für Nationalmannschaften sind dagegen nicht verfügbar.

Wie oft werden die Daten aktualisiert?

Jede Woche. Die Statistiken enthalten die zuletzt gespielten Spieltage jeder abgedeckten Liga.

Wie erhalte ich einen API-Schlüssel und die Preise?

Der API-Zugang ist auf Anfrage verfügbar. Kontaktiere uns mit den Ligen, die dich interessieren: Wir teilen dir die Preise mit und aktivieren deinen Schlüssel.

Schnellstart

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

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

Authentifizierung

Jede Anfrage muss deinen API-Schlüssel im HTTP-Header enthalten X-API-Key.

X-API-Key: dk_live_a1b2c3d4e5f6...

Best Practices :

  • Committe niemals einen Schlüssel in ein Git-Repository
  • Verwende einen eigenen Schlüssel pro Umgebung (Prod, Staging, Dev)
  • Widerrufe kompromittierte Schlüssel sofort
  • Lege für temporäre Schlüssel ein Ablaufdatum fest

Spieler-Identifikatoren

In der API existieren zwei Spieler-Identifikatoren: wissen Sie, welchen Sie speichern sollten.

  • player_id : identifiziert eine ZEILE Spieler × Kontext (Saison, Verein, Wettbewerb). Er ändert sich jede Saison, bei jedem Transfer und zwischen Liga und Europapokal: nicht als dauerhaften Schlüssel speichern.
  • datascout_id : identifiziert eine PERSON (Format ds_ + 16 Zeichen): stabil über Saisons, Transfers und Wettbewerbe hinweg. Dies ist der empfohlene Schlüssel zur Indexierung Ihrer Daten.
  • datascout_id ist in jeder Spieler-Antwort enthalten (null, wenn die Zeile noch nicht verknüpft ist, vorübergehend).
  • Er wird überall akzeptiert, wo eine player_id erwartet wird (/v1/players/:id/*-Routen, player_ids in /v1/compare und /v1/fit-score).
  • Zum Aufbau Ihres Referenzsystems: POST /v1/players/resolve-batch, dann die datascout_id jedes Spielers speichern. GET /v1/players/:id/history liefert die Zuordnung pro Saison.

Rate Limiting

Pro Ligue-Tarif: 10.000 Anfragen/Tag. Pro Full-Tarif: unbegrenzt. Jede Antwort enthält die folgenden Header:

  • X-RateLimit-Limit: Tageslimit
  • X-RateLimit-Remaining: verbleibende Anfragen
  • X-RateLimit-Reset: Reset-Datum (ISO 8601)

Fehlercodes

CodeBedeutung
200Erfolg
400Fehlende oder ungültige Parameter
401API-Schlüssel fehlt, ungültig oder abgelaufen
403Tarif unzureichend oder Liga nicht zugänglich
404Ressource nicht gefunden
429Rate Limit überschritten
500Serverfehler

Endpoints

Profil

Identität des aufrufenden API-Schlüssels

Referenz

Metadaten: Ligen, Saisons, Teams

Spieler

Suche, Profile, Statistiken, ähnliche Spieler

Teams

Profil, Kader, Ähnlichkeit, Head-to-Head-Vergleich

Trainer

Suche, Profil, Karriere und taktisches Profil der Trainer

Ranglisten

Top-Spieler nach Rolle oder Statistik

Glossar

Maschinenlesbare Dokumentation der Statistiken und Indizes

Scouting

Erweiterte Multi-Kriterien-Suche

Meine Ressourcen

In deinem DataScout-Konto gespeicherte Indizes und Presets

Vergleich

Verteilung von Spielern auf 2 gekreuzten Statistiken

Positionsrollen (31 Profile)

Verwendbar in /v1/rankings / /v1/scouting über den Parameter role.

Sechs Schlüssel wurden am 18. September 2026 umbenannt, damit sie zu den angezeigten Bezeichnungen passen. Die alten Schlüssel werden weiterhin akzeptiert: GET /v1/enums nennt zu jeder umbenannten Rolle den früheren Schlüssel im Feld deprecated_key.

Torwarte

  • gardien_stoppeur
  • gardien_moderne
  • gardien_relanceur

Innenverteidiger

  • defenseur_stoppeur
  • defenseur_relanceur
  • defenseur_mobile
  • defenseur_aerien

Außenverteidiger

  • lateral_defensif
  • lateral_offensif
  • lateral_athletique
  • lateral_passeur

Defensive Mittelfeldspieler

  • milieu_progressif
  • milieu_recuperateur
  • meneur_de_jeu_en_retrait

Zentrale Mittelfeldspieler

  • milieu_box_to_box
  • mezzala
  • milieu_relayeur
  • milieu_ratisseur

Offensive Mittelfeldspieler

  • meneur_de_jeu
  • meneur_percuteur
  • meneur_travailleur
  • meneur_de_jeu_excentre

Flügelspieler

  • ailier_travailleur
  • ailier_de_profondeur
  • ailier_provocateur
  • ailier_buteur

Stürmer

  • faux_9
  • attaquant_pivot
  • attaquant_de_pressing
  • attaquant_de_profondeur
  • renard_des_surfaces

Neu berechnete Werte

Der Versionsvertrag betrifft die Form der Antworten, nicht die Werte selbst. Unsere Kennzahlen (Leistungsindex, Rollen, Ähnlichkeit, Projektion, geschätzter Marktwert) werden wöchentlich neu berechnet und ihre Methoden entwickeln sich weiter. Legen Sie keine festen Schwellenwerte auf einen Score, aktualisieren Sie gespeicherte Werte und verwenden Sie datascout_id als einzigen dauerhaften Schlüssel. Änderungen, die Werte verschieben, werden den Inhabern aktiver Schlüssel per E-Mail angekündigt.

Codebeispiele

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_...')
}
Möchtest du DataScout in deine Tools integrieren? Der API-Zugang ist auf Anfrage verfügbar.

Teste die API live

Probiere die Endpoints direkt in deinem Browser aus, ganz ohne Code.