Skip to main content

​
Partidas

Os endpoints de partidas permitem listar jogos de um campeonato e consultar placares, com suporte a filtros por rodada, status, time e intervalo de datas.

​
Endpoints disponíveis

MétodoEndpointDescrição
GET/v1/campeonatos/:id/partidasTodas as partidas de um campeonato (com filtros)
GET/v1/partidas/ao-vivoPartidas em andamento agora
O endpoint de listagem por campeonato também está documentado na seção Campeonatos, pois faz parte da hierarquia campeonato → partida.

​
Status das partidas

Todas as partidas retornam um campo status com um dos seguintes valores:
StatusSignificado
aguardandoA partida está agendada, mas ainda não começou. Placar retorna null.
ao_vivoA partida está em andamento.
encerradoA partida foi finalizada. Placar definitivo.
adiadoA partida foi adiada. Não há placar.

​
Cache e atualização

EndpointTTL do cache
/v1/campeonatos/:id/partidas60 segundos
/v1/partidas/ao-vivo15 segundos

​
Filtros de partidas por campeonato

O endpoint /v1/campeonatos/:id/partidas aceita os seguintes parâmetros:
ParâmetroTipoDescriçãoExemplo
rodadaintegerSomente partidas de uma rodada?rodada=5
statusstringSomente partidas com aquele status?status=encerrado
time_idintegerSomente jogos em que o time participa (mandante ou visitante)?time_id=1
data_iniciostringData mínima no formato YYYY-MM-DD?data_inicio=2026-03-01
data_fimstringData máxima no formato YYYY-MM-DD?data_fim=2026-03-31
paginaintegerPágina desejada (padrão: 1)?pagina=2
por_paginaintegerItens por página, de 1 a 100 (padrão: 15)?por_pagina=10

​
Exemplo — partidas encerradas do Flamengo no Brasileirão

curl -H "Authorization: Bearer test-api-key-free-sandbox" \
  "https://api.dadosfutebol.com.br/v1/campeonatos/1/partidas?time_id=1&status=encerrado"

{
  "data": [
    {
      "id": 1,
      "rodada_id": 1,
      "rodada_numero": 1,
      "rodada_nome": "1ª Rodada",
      "time_mandante": { "id": 1, "nome": "Flamengo", "sigla": "FLA", "escudo_url": null },
      "time_visitante": { "id": 2, "nome": "Palmeiras", "sigla": "PAL", "escudo_url": null },
      "placar_mandante": 2,
      "placar_visitante": 1,
      "disputa_penalti": false,
      "penalti": null,
      "status": "encerrado",
      "slug": "flamengo-palmeiras-1",
      "data_realizacao": "08/03/2026",
      "hora_realizacao": "16:00",
      "data_hora_realizacao": "2026-03-08T16:00:00-03:00",
      "estadio": "Maracanã"
    }
  ],
  "meta": {
    "campeonato_id": 1,
    "total": 3,
    "por_pagina": 15,
    "pagina_atual": 1,
    "ultima_pagina": 1
  }
}

​
GET /v1/partidas/ao-vivo

Retorna todas as partidas que estão acontecendo no momento em qualquer campeonato. Cache de 15 segundos. 
curl -H "Authorization: Bearer test-api-key-free-sandbox" \
  https://api.dadosfutebol.com.br/v1/partidas/ao-vivo

{
  "data": [
    {
      "id": 9,
      "campeonato_id": 1,
      "campeonato_nome": "Campeonato Brasileiro Série A",
      "rodada_numero": 3,
      "time_mandante": { "id": 1, "nome": "Flamengo", "sigla": "FLA", "escudo_url": null },
      "time_visitante": { "id": 7, "nome": "Grêmio", "sigla": "GRE", "escudo_url": null },
      "placar_mandante": 1,
      "placar_visitante": 0,
      "status": "ao_vivo",
      "estadio": "Maracanã"
    }
  ],
  "meta": { "total": 1 }
}