Documentação da API: Integra os dados de futebol

Visão geral

Que dados?

Estatísticas detalhadas por jogador e por equipa, índices de desempenho por papel, pontos fortes e fracos, valores de mercado estimados, projeções entre campeonatos, perfis semelhantes e pontuações de adequação jogador-clube.

Que cobertura?

Mais de 100 campeonatos masculinos e femininos na Europa, Américas, Ásia e África, do Big 5 às divisões inferiores e campeonatos jovens, além das taças europeias (Liga dos Campeões, Europa League, Conference League). O endpoint /v1/leagues devolve os campeonatos acessíveis com a tua chave.

Qual a atualidade dos dados?

Os dados são atualizados todas as semanas, à medida que as jornadas dos campeonatos são disputadas.

Como funciona o acesso?

Subscrição mensal por campeonato: cada subscrição cobre todos os jogadores e equipas do campeonato escolhido, com todas as suas estatísticas, taças europeias incluídas. Preços sob consulta.

Perguntas frequentes

As estatísticas cobrem a Liga dos Campeões ou as seleções nacionais?

As taças europeias (Liga dos Campeões, Europa League, Conference League) estão incluídas em qualquer subscrição da API sem custo adicional: os jogadores que nelas participam têm estatísticas separadas das do seu campeonato. As estatísticas ao serviço das seleções nacionais, no entanto, não estão disponíveis.

Com que frequência os dados são atualizados?

Todas as semanas. As estatísticas incluem as últimas jornadas disputadas de cada campeonato coberto.

Como obtenho uma chave API e os preços?

O acesso à API está disponível mediante pedido. Contacta-nos indicando os campeonatos que te interessam: comunicaremos os preços e ativaremos a tua chave.

Início rápido

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

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

Autenticação

Todos os pedidos devem incluir a tua chave API no cabeçalho HTTP X-API-Key.

X-API-Key: dk_live_a1b2c3d4e5f6...

Boas práticas :

Nunca faças commit de uma chave num repositório Git
Utiliza uma chave por ambiente (produção, staging, desenvolvimento)
Revoga imediatamente qualquer chave comprometida
Define uma data de expiração para chaves temporárias

Identificadores de jogadores

Na API coexistem dois identificadores de jogador: saiba qual armazenar.

player_id : identifica uma LINHA jogador × contexto (época, clube, competição). Muda a cada época, a cada transferência e entre campeonato e competição europeia: não o armazene como chave duradoura.
datascout_id : identifica uma PESSOA (formato ds_ + 16 caracteres): estável entre épocas, transferências e competições. É a chave recomendada para indexar os seus dados.
datascout_id está presente em todas as respostas de jogador (null se a linha ainda não estiver associada, transitório).
É aceite em qualquer lugar onde um player_id seja esperado (rotas /v1/players/:id/*, player_ids de /v1/compare e /v1/fit-score).
Para iniciar o seu referencial: POST /v1/players/resolve-batch e armazene o datascout_id de cada jogador. GET /v1/players/:id/history devolve a correspondência por época.

Limitação de taxa

Plano Pro Ligue: 10 000 pedidos/dia. Plano Pro Full: ilimitado. Cada resposta inclui os seguintes cabeçalhos:

X-RateLimit-Limit: limite diário
X-RateLimit-Remaining: pedidos restantes
X-RateLimit-Reset: data de reset (ISO 8601)

Códigos de erro

Código	Significado
200	Sucesso
400	Parâmetros em falta ou inválidos
401	Chave API em falta, inválida ou expirada
403	Plano insuficiente ou liga não acessível
404	Recurso não encontrado
429	Rate limit excedido
500	Erro do servidor

Endpoints

Perfil

Identidade da chave que chama a API

Referência

Metadados: ligas, épocas, equipas

Jogadores

Pesquisa, fichas, estatísticas, perfis semelhantes

Equipas

Ficha, plantel, semelhança, comparação direta

Treinadores

Pesquisa, ficha, carreira e perfil tático dos treinadores

Classificações

Melhores jogadores por função ou por estatística

Glossário

Documentação legível por máquina das estatísticas e índices

Scouting

Pesquisa avançada multicritério

Os meus recursos

Índices e presets guardados na tua conta DataScout

Comparação

Distribuição de jogadores em 2 estatísticas cruzadas

Funções posicionais (27 perfis)

Utilizáveis em /v1/rankings / /v1/scouting através do parâmetro role.

Guarda-redes

gardien_stoppeur
gardien_moderne

Defesas centrais

defenseur_stoppeur
defenseur_relanceur
defenseur_moderne
defenseur_athletique

Laterais

arriere_lateral
lateral_offensif
lateral_interieur

Médios defensivos

milieu_sentinelle
milieu_recuperateur
meneur_de_jeu_en_retrait

Médios centro

milieu_box_to_box
mezzala
milieu_relayeur
milieu_ratisseur

Médios ofensivos

meneur_de_jeu
meneur_de_jeu_excentre

Extremos

ailier_defensif
ailier_interieur
ailier_de_profondeur
ailier_provocateur
ailier_buteur

Avançados

faux_9
attaquant_pivot
attaquant_de_pressing
attaquant_de_profondeur
renard_des_surfaces
attaquant_complet

Exemplos de código

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

Documentação da API