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étodo	Endpoint	Descrição
`GET`	`/v1/times`	Busca times por nome ou sigla
`GET`	`/v1/times/:id/jogadores`	Elenco de um time específico
`GET`	`/v1/jogadores`	Busca jogadores por nome
`GET`	`/v1/jogadores/:id`	Detalhes 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âmetro	Tipo	Obrigatório	Descrição	Exemplo
`q`	string	Sim	Busca por nome ou sigla, mínimo 2 chars, case-insensitive	`?q=Fla`
`tipo`	string	Não	Filtra 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://assets.dadosfutebol.com.br/escudos/flamengo.png"
    },
    {
      "id": 173,
      "nome": "Floresta-CE",
      "tipo": "clube",
      "sigla": "FLO",
      "escudo_url": "https://assets.dadosfutebol.com.br/escudos/floresta-ce.png"
    },
    {
      "id": 4,
      "nome": "Fluminense",
      "tipo": "clube",
      "sigla": "FLU",
      "escudo_url": "https://assets.dadosfutebol.com.br/escudos/fluminense.png"
    },
    {
      "id": 316,
      "nome": "Fluminense do Itaum",
      "tipo": "clube",
      "sigla": "FDI",
      "escudo_url": "https://assets.dadosfutebol.com.br/escudos/fluminense-do-itaum.png"
    },
    {
      "id": 770,
      "nome": "Fluminense-PI",
      "tipo": "clube",
      "sigla": "FLU",
      "escudo_url": null
    }
  ],
  "meta": {
    "total": 5
  }
}

escudo_url sempre aponta para imagens hospedadas em assets.dadosfutebol.com.br (ou para o proxy de bandeiras da API, no caso de seleções). Quando ainda não temos a imagem do time, vem null — nunca uma URL de terceiro.

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ódigo	Motivo
`422`	`?q=` ausente ou com menos de 2 caracteres
`401`	API 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 SUA_API_KEY" \
  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ódigo	Motivo
`404`	Time 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âmetro	Tipo	Obrigatório	Descrição	Exemplo
`q`	string	Sim	Busca parcial pelo nome do jogador, mínimo 2 chars	`?q=Pedro`
`time_id`	integer	Não	Restringe a busca a um time específico	`?time_id=1`
`posicao`	string	Não	Filtra por posição (veja valores abaixo)	`?posicao=atacante`

Valores de posição

Valor	Descrição
`goleiro`	Goleiro
`zagueiro`	Zagueiro
`lateral`	Lateral (esquerdo ou direito)
`volante`	Volante / Médio defensivo
`meia`	Meia (armador, meia-atacante, etc.)
`atacante`	Atacante / 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://assets.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://assets.dadosfutebol.com.br/escudos/maranguape.png"
      }
    }
  ],
  "meta": {
    "total": 10
  }
}

Erros possíveis

Código	Motivo
`422`	`?q=` ausente ou com menos de 2 caracteres
`401`	API 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://assets.dadosfutebol.com.br/escudos/maranguape.png"
    }
  }
}

Código	Motivo
`404`	Jogador não encontrado com o ID informado

Campos da resposta de jogador

Campo	Tipo	Descrição
`id`	integer	Identificador único do jogador
`nome_popular`	string	Apelido ou nome de guerra (pode ser `null`)
`nome`	string	Nome completo do jogador
`idade`	integer	Idade em anos (ou `null` se não cadastrada)
`posicao`	string	Posição: `goleiro`, `zagueiro`, `lateral`, `volante`, `meia` ou `atacante`
`numero_camisa`	integer	Número da camisa no time atual (ou `null`)
`gols`	integer	Total de gols marcados na temporada
`time`	object	Dados do clube: `id`, `nome`, `sigla`, `escudo_url`

Introdução

Endpoints

Integrações

Times e Jogadores

Times e Jogadores

Endpoints disponíveis

GET /v1/times

Parâmetros de query

Exemplo — busca por “fl”

Exemplo — erro sem parâmetro de busca

Erros possíveis

GET /v1/times/:id/jogadores

GET /v1/jogadores

Parâmetros de query

Valores de posição

Exemplo — busca por “felipe”

Erros possíveis

GET /v1/jogadores/:id

Campos da resposta de jogador

​Times e Jogadores

​Endpoints disponíveis

​GET /v1/times

​Parâmetros de query

​Exemplo — busca por “fl”

​Exemplo — erro sem parâmetro de busca

​Erros possíveis

​GET /v1/times/:id/jogadores

​GET /v1/jogadores

​Parâmetros de query

​Valores de posição

​Exemplo — busca por “felipe”

​Erros possíveis

​GET /v1/jogadores/:id

​Campos da resposta de jogador

Times e Jogadores

Endpoints disponíveis

GET /v1/times

Parâmetros de query

Exemplo — busca por “fl”

Exemplo — erro sem parâmetro de busca

Erros possíveis

GET /v1/times/:id/jogadores

GET /v1/jogadores

Parâmetros de query

Valores de posição

Exemplo — busca por “felipe”

Erros possíveis

GET /v1/jogadores/:id

Campos da resposta de jogador