API Documentation: Integrate Football Data

Overview

What data?

Detailed player and team statistics, role-based performance indices, strengths and weaknesses, estimated market values, cross-league projections, similar player profiles and player-club fit scores.

What coverage?

Over 100 men's and women's leagues across Europe, the Americas, Asia and Africa, from the Big 5 to lower divisions and youth leagues, plus the European cups (Champions League, Europa League, Conference League). The /v1/leagues endpoint returns the leagues accessible with your key.

How fresh is the data?

Data is updated every week, as each round of league fixtures is played.

How does access work?

Monthly subscription per league: each subscription covers every player and team in the chosen league, with all their statistics, European cups included. Pricing on request.

Frequently asked questions

Do the statistics cover the Champions League or national teams?

The European cups (Champions League, Europa League, Conference League) are included with any API subscription at no extra cost: players who take part in them have statistics that are separate from their league ones. National team statistics, however, are not available.

How often is the data updated?

Every week. Statistics include the latest rounds played in each covered league.

How do I get an API key and pricing?

API access is available on request. Contact us with the leagues you are interested in: we will share pricing and activate your key.

Quickstart

Base URL : https://api.datascout.fr/v1

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

Authentication

Every request must include your API key in the HTTP header X-API-Key.

X-API-Key: dk_live_a1b2c3d4e5f6...

Best practices :

Never commit a key to a Git repository
Use one key per environment (prod, staging, dev)
Revoke any compromised key immediately
Set an expiration date for temporary keys

Player identifiers

Two player identifiers coexist in the API: know which one to store.

player_id : identifies a player ROW × context (season, club, competition). It changes every season, on every transfer, and between league and European competition: do not store it as a durable key.
datascout_id : identifies a PERSON (format ds_ + 16 characters): stable across seasons, transfers and competitions. This is the recommended key to index your data.
datascout_id is present in every player response (null if the row is not linked yet, transient).
It is accepted anywhere a player_id is expected (/v1/players/:id/* routes, player_ids in /v1/compare and /v1/fit-score).
To bootstrap your referential: POST /v1/players/resolve-batch, then store each player's datascout_id. GET /v1/players/:id/history returns the per-season mapping.

Rate limiting

Pro League plan: 10,000 requests/day. Pro Full plan: unlimited. Every response includes the following headers:

X-RateLimit-Limit: daily limit
X-RateLimit-Remaining: remaining requests
X-RateLimit-Reset: reset date (ISO 8601)

Error codes

Code	Meaning
200	Success
400	Missing or invalid parameters
401	Missing, invalid, or expired API key
403	Insufficient plan or inaccessible league
404	Resource not found
429	Rate limit exceeded
500	Server error

Endpoints

Profile

Identity of the calling API key

Reference

Metadata: leagues, seasons, teams

Players

Search, profiles, stats, similar players

Teams

Team profile, squad, similarity, head-to-head comparison

Coaches

Search, profile, career and tactical fingerprint of coaches

Rankings

Top players by role or by statistic

Glossary

Machine-readable documentation of stats and indices

Scouting

Advanced multi-criteria search

My resources

Stored indexes and presets from your DataScout account

Comparison

Player distribution across two stats

Positional roles (27 profiles)

Usable in /v1/rankings / /v1/scouting via the parameter role.

Goalkeepers

gardien_stoppeur
gardien_moderne

Center backs

defenseur_stoppeur
defenseur_relanceur
defenseur_moderne
defenseur_athletique

Full backs

arriere_lateral
lateral_offensif
lateral_interieur

Defensive midfielders

milieu_sentinelle
milieu_recuperateur
meneur_de_jeu_en_retrait

Central midfielders

milieu_box_to_box
mezzala
milieu_relayeur
milieu_ratisseur

Attacking midfielders

meneur_de_jeu
meneur_de_jeu_excentre

Wingers

ailier_defensif
ailier_interieur
ailier_de_profondeur
ailier_provocateur
ailier_buteur

Forwards

faux_9
attaquant_pivot
attaquant_de_pressing
attaquant_de_profondeur
renard_des_surfaces
attaquant_complet

Code examples

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 Documentation