API Dados Futebol

A API Dados Futebol é uma API REST que fornece dados estruturados do futebol brasileiro: campeonatos, rodadas, partidas, tabelas de classificação, artilharia e elencos dos clubes. Todas as respostas são em português, com chaves JSON semânticas como placar_mandante, campeonato_id e ao_vivo. A API segue o padrão REST sobre HTTPS, retorna JSON em todas as rotas e usa autenticação via API Key no header Authorization.

O que você pode fazer

Campeonatos e Tabela

Liste competições, filtre por temporada e status, e consulte a classificação completa com pontos, saldo e aproveitamento.

Partidas

Consulte placares e histórico de jogos, com filtros por rodada, status, time e intervalo de datas.

Times e Jogadores

Busque clubes por nome ou sigla, veja elencos completos e consulte artilheiros por campeonato.

Autenticação e Limites

Entenda como usar sua API Key, os planos disponíveis e os headers de rate limiting retornados em cada resposta.

Assistentes de IA (MCP)

Conecte os dados a Claude e Cursor via Model Context Protocol — 23 ferramentas que espelham os endpoints da API.

Como funciona

Toda requisição precisa de uma API Key enviada como Bearer Token. A API valida a key, aplica o rate limit do plano correspondente e retorna os dados em JSON. As respostas de listagem seguem sempre o mesmo envelope:

{
  "data": [ ... ],
  "meta": {
    "total": 2,
    "por_pagina": 15,
    "pagina_atual": 1,
    "ultima_pagina": 1
  }
}

Respostas de item único omitem o meta e retornam apenas "data": { ... }. Erros retornam um objeto com "erro" e "mensagem" em português.

Início rápido

1. Obtenha sua API Key

Solicite sua key pelo painel administrativo ou entre em contato. A API roda somente em produção; cada cliente utiliza sua própria key.

2. Faça sua primeira requisição

curl -H "Authorization: Bearer SUA_API_KEY" \
  https://api.dadosfutebol.com.br/v1/campeonatos

Substitua SUA_API_KEY pela key que você recebeu.

3. Resposta esperada

{
  "data": [
    {
      "id": 3,
      "nome": "Brasileirão Série A",
      "temporada": "2026",
      "tipo": "pontos-corridos",
      "status": "em_andamento"
    },
    {
      "id": 62,
      "nome": "Copa do Brasil",
      "temporada": "2026",
      "tipo": "mata-mata",
      "status": "em_andamento"
    }
  ],
  "meta": {
    "total": 2,
    "por_pagina": 15,
    "pagina_atual": 1,
    "ultima_pagina": 1
  }
}

Base URL

Ambiente	URL base
Produção	`https://api.dadosfutebol.com.br`

Todos os endpoints começam com o prefixo /v1:

GET https://api.dadosfutebol.com.br/v1/campeonatos
GET https://api.dadosfutebol.com.br/v1/campeonatos/3/partidas

Convenções gerais

Aspecto	Comportamento
Formato	JSON (`Content-Type: application/json`)
Autenticação	`Authorization: Bearer {api_key}`
Datas	ISO 8601 com timezone (`2026-04-19T16:00:00-03:00`)
Erros	Sempre em português com campos `erro` e `mensagem`
Cache	Listagens: 60s

Referência de Parâmetros

Todos os parâmetros aceitos pela API, agrupados por tipo.

Parâmetros de path (obrigatórios)

Informados na URL. Sempre inteiros.

Parâmetro	Onde aparece	Significado
`:id`	`/v1/campeonatos/:id`, `/v1/partidas/:id/...`, `/v1/jogadores/:id`	Identificador único do recurso
`:campeonatoId`	`/v1/campeonatos/:campeonatoId/rodadas`, `.../partidas`, `.../tabela`, `.../artilharia`, `.../fases`, `.../chave`	ID do campeonato pai
`:faseId`	`/v1/campeonatos/:id/fases/:faseId`, `.../fases/:faseId/tabela`	ID da fase dentro do campeonato
`:timeId`	`/v1/times/:timeId/jogadores`	ID do time

Parâmetros de busca (obrigatórios)

Parâmetro	Endpoints	Tipo	Significado
`q`	`/v1/times`, `/v1/jogadores`	string (min: 2 chars)	Termo de busca por nome. Retorna 422 se ausente ou menor que 2 caracteres.

Filtros (opcionais)

Parâmetro	Endpoints	Tipo	Valores aceitos	Significado
`temporada`	`/v1/campeonatos`	string	Ano com 4 dígitos (ex: `2026`)	Filtra campeonatos pelo ano da temporada. Sem filtro retorna todos.
`status`	`/v1/campeonatos`	string	`em_andamento`, `encerrado`	Filtra pelo estado atual do campeonato.
`tipo`	`/v1/campeonatos`, `/v1/times`	string	`pontos-corridos`, `mata-mata` (campeonatos) / `clube`, `selecao` (times)	Filtra pelo formato de disputa ou tipo de time.
`rodada`	`/v1/campeonatos/:id/partidas`	integer	Número da rodada (ex: `5`)	Retorna apenas partidas daquela rodada.
`status`	`/v1/campeonatos/:id/partidas`	string	`aguardando`, `ao_vivo`, `encerrado`, `adiado`	Filtra partidas pelo status atual.
`time_id`	`/v1/campeonatos/:id/partidas`, `/v1/jogadores`	integer	ID de um time	Retorna jogos onde o time participa (mandante ou visitante), ou jogadores do time.
`data_inicio`	`/v1/campeonatos/:id/partidas`	string	Formato `YYYY-MM-DD`	Limite inferior de data das partidas (inclusive).
`data_fim`	`/v1/campeonatos/:id/partidas`	string	Formato `YYYY-MM-DD`	Limite superior de data das partidas (inclusive).
`posicao`	`/v1/jogadores`	string	`goleiro`, `zagueiro`, `lateral`, `volante`, `meia`, `atacante`	Filtra jogadores pela posição em campo.

Paginação (opcionais)

Disponível em /v1/campeonatos e /v1/campeonatos/:id/partidas.

Parâmetro	Tipo	Padrão	Limites	Significado
`pagina`	integer	`1`	min: 1	Número da página desejada.
`por_pagina`	integer	`15`	min: 1, max: 100	Quantidade de itens por página.

Endpoints de busca (/v1/times e /v1/jogadores) retornam no máximo 20 resultados sem paginação. Use termos mais específicos para refinar.

Valores de enum

Status do campeonato

Valor	Significado
`agendado`	Competição ainda não começou
`andamento`	Competição em curso
`encerrado`	Competição finalizada

Tipo do campeonato

Valor	Significado
`pontos-corridos`	Todos jogam contra todos (ex: Brasileirão Série A)
`mata-mata`	Eliminatórias com chaves (ex: Copa do Brasil)

Status da partida

Valor	Significado
`aguardando`	Partida agendada, placar retorna `null`
`ao_vivo`	Partida em andamento
`encerrado`	Partida finalizada com placar definitivo
`adiado`	Partida adiada, sem placar

Posição do jogador

Valor	Significado
`goleiro`	Goleiro
`zagueiro`	Zagueiro
`lateral`	Lateral (esquerdo ou direito)
`volante`	Volante / Médio defensivo
`meia`	Meia / Armador
`atacante`	Atacante / Centroavante / Ponta

Introdução

Endpoints

Integrações

Introdução

API Dados Futebol

O que você pode fazer

Campeonatos e Tabela

Partidas

Times e Jogadores

Autenticação e Limites

Assistentes de IA (MCP)

Como funciona

Início rápido

1. Obtenha sua API Key

2. Faça sua primeira requisição

3. Resposta esperada

Base URL

Convenções gerais

Referência de Parâmetros

Parâmetros de path (obrigatórios)

Parâmetros de busca (obrigatórios)

Filtros (opcionais)

Paginação (opcionais)

Valores de enum

Status do campeonato

Tipo do campeonato

Status da partida

Posição do jogador

​API Dados Futebol

​O que você pode fazer

Campeonatos e Tabela

Partidas

Times e Jogadores

Autenticação e Limites

Assistentes de IA (MCP)

​Como funciona

​Início rápido

​1. Obtenha sua API Key

​2. Faça sua primeira requisição

​3. Resposta esperada

​Base URL

​Convenções gerais

​Referência de Parâmetros

​Parâmetros de path (obrigatórios)

​Parâmetros de busca (obrigatórios)

​Filtros (opcionais)

​Paginação (opcionais)

​Valores de enum

​Status do campeonato

​Tipo do campeonato

​Status da partida

​Posição do jogador

API Dados Futebol

O que você pode fazer

Como funciona

Início rápido

1. Obtenha sua API Key

2. Faça sua primeira requisição

3. Resposta esperada

Base URL

Convenções gerais

Referência de Parâmetros

Parâmetros de path (obrigatórios)

Parâmetros de busca (obrigatórios)

Filtros (opcionais)

Paginação (opcionais)

Valores de enum

Status do campeonato

Tipo do campeonato

Status da partida

Posição do jogador