Skip to main content

​
Times e Jogadores

Os endpoints de times e jogadores funcionam como busca, não como listagem. É obrigatório informar ao menos 2 caracteres no parâmetro ?q= para obter resultados — sem ele a API retorna 422. Isso evita a extração em massa do banco de dados.

​
Endpoints disponíveis

MétodoEndpointDescrição
GET/v1/timesBusca times por nome ou sigla
GET/v1/times/:id/jogadoresElenco de um time específico
GET/v1/jogadoresBusca jogadores por nome
GET/v1/jogadores/:idDetalhes de um jogador específico

​
GET /v1/times

Busca clubes por nome ou sigla. O parâmetro ?q= é obrigatório com ao menos 2 caracteres. Retorna no máximo 20 resultados, sem paginação.
Requisições sem ?q= ou com menos de 2 caracteres retornam 422 Unprocessable Entity.

​
Parâmetros de query

ParâmetroTipoObrigatórioDescriçãoExemplo
qstringSimBusca por nome ou sigla, mínimo 2 chars, case-insensitive?q=Fla
tipostringNãoFiltra por tipo: clube ou selecao?tipo=clube

​
Exemplo — busca por “fl”

curl -H "Authorization: Bearer SEU_TOKEN" \
  "https://api.dadosfutebol.com.br/v1/times?q=fl"

{
  "data": [
    {
      "id": 1,
      "nome": "Flamengo",
      "tipo": "clube",
      "sigla": "FLA",
      "escudo_url": "https://api.dadosfutebol.com.br/escudos/flamengo.png"
    },
    {
      "id": 173,
      "nome": "Floresta-CE",
      "tipo": "clube",
      "sigla": "FLO",
      "escudo_url": "https://api.dadosfutebol.com.br/escudos/floresta-ce.png"
    },
    {
      "id": 4,
      "nome": "Fluminense",
      "tipo": "clube",
      "sigla": "FLU",
      "escudo_url": "https://api.dadosfutebol.com.br/escudos/fluminense.png"
    },
    {
      "id": 316,
      "nome": "Fluminense do Itaum",
      "tipo": "clube",
      "sigla": "FDI",
      "escudo_url": "https://api.dadosfutebol.com.br/escudos/fluminense-do-itaum.png"
    },
    {
      "id": 770,
      "nome": "Fluminense-PI",
      "tipo": "clube",
      "sigla": "FLU",
      "escudo_url": "https://cdn-img.zerozero.pt/img/logos/equipas/3248_imgbank.png"
    }
  ],
  "meta": {
    "total": 5
  }
}

​
Exemplo — erro sem parâmetro de busca

{
  "erro": "Parâmetro obrigatório",
  "mensagem": "Informe ao menos 2 caracteres no parâmetro ?q= para buscar times."
}

​
Erros possíveis

CódigoMotivo
422?q= ausente ou com menos de 2 caracteres
401API Key inválida ou ausente

​
GET /v1/times/:id/jogadores

Retorna o elenco completo de um time específico, ordenado por posição e nome. 
curl -H "Authorization: Bearer test-api-key-free-sandbox" \
  https://api.dadosfutebol.com.br/v1/times/1/jogadores

{
  "data": [
    {
      "id": 1,
      "nome_popular": "Pedro",
      "nome": "Pedro Guilherme",
      "idade": 27,
      "posicao": "atacante",
      "numero_camisa": 9,
      "gols": 15
    },
    {
      "id": 2,
      "nome_popular": "Everton Ribeiro",
      "nome": "Everton Ribeiro",
      "idade": 35,
      "posicao": "meia",
      "numero_camisa": 7,
      "gols": 4
    }
  ],
  "meta": {
    "total": 25,
    "time": { "id": 1, "nome": "Flamengo", "sigla": "FLA", "escudo_url": null }
  }
}
CódigoMotivo
404Time não encontrado com o ID informado

​
GET /v1/jogadores

Busca jogadores por nome. O parâmetro ?q= é obrigatório com ao menos 2 caracteres. Retorna no máximo 20 resultados, sem paginação.
Requisições sem ?q= ou com menos de 2 caracteres retornam 422 Unprocessable Entity.

​
Parâmetros de query

ParâmetroTipoObrigatórioDescriçãoExemplo
qstringSimBusca parcial pelo nome do jogador, mínimo 2 chars?q=Pedro
time_idintegerNãoRestringe a busca a um time específico?time_id=1
posicaostringNãoFiltra por posição (veja valores abaixo)?posicao=atacante

​
Valores de posição

ValorDescrição
goleiroGoleiro
zagueiroZagueiro
lateralLateral (esquerdo ou direito)
volanteVolante / Médio defensivo
meiaMeia (armador, meia-atacante, etc.)
atacanteAtacante / Centroavante / Ponta

​
Exemplo — busca por “felipe”

curl -H "Authorization: Bearer SEU_TOKEN" \
  "https://api.dadosfutebol.com.br/v1/jogadores?q=felipe"

{
  "data": [
    {
      "id": 163,
      "nome_popular": null,
      "nome": "Everton Felipe",
      "idade": null,
      "posicao": "Atacante",
      "numero_camisa": null,
      "gols": 0,
      "time": {
        "id": 382,
        "nome": "Pombal EC",
        "sigla": "PE",
        "escudo_url": "https://api.dadosfutebol.com.br/escudos/pombal-ec.png"
      }
    },
    {
      "id": 638,
      "nome_popular": null,
      "nome": "Felipe Hulk",
      "idade": null,
      "posicao": "Atacante",
      "numero_camisa": null,
      "gols": 0,
      "time": {
        "id": 175,
        "nome": "Maranguape",
        "sigla": "MAR",
        "escudo_url": "https://api.dadosfutebol.com.br/escudos/maranguape.png"
      }
    }
  ],
  "meta": {
    "total": 10
  }
}

​
Erros possíveis

CódigoMotivo
422?q= ausente ou com menos de 2 caracteres
401API Key inválida ou ausente

​
GET /v1/jogadores/:id

Retorna os dados completos de um jogador específico pelo seu ID. 
curl -H "Authorization: Bearer SEU_TOKEN" \
  https://api.dadosfutebol.com.br/v1/jogadores/638

{
  "data": {
    "id": 638,
    "nome_popular": null,
    "nome": "Felipe Hulk",
    "idade": null,
    "posicao": "Atacante",
    "numero_camisa": null,
    "gols": 0,
    "time": {
      "id": 175,
      "nome": "Maranguape",
      "sigla": "MAR",
      "escudo_url": "https://api.dadosfutebol.com.br/escudos/maranguape.png"
    }
  }
}
CódigoMotivo
404Jogador não encontrado com o ID informado

​
Campos da resposta de jogador

CampoTipoDescrição
idintegerIdentificador único do jogador
nome_popularstringApelido ou nome de guerra (pode ser null)
nomestringNome completo do jogador
idadeintegerIdade em anos (ou null se não cadastrada)
posicaostringPosição: goleiro, zagueiro, lateral, volante, meia ou atacante
numero_camisaintegerNúmero da camisa no time atual (ou null)
golsintegerTotal de gols marcados na temporada
timeobjectDados do clube: id, nome, sigla, escudo_url