Para desenvolvedores

API do metrô e trens de São Paulo

Situação ao vivo e histórico oficial das linhas, coletados a cada 30 segundos dos canais públicos das operadoras. Respostas em JSON, com uma chave gratuita. São os mesmos dados do painel de status do metrô e trens e das páginas de cada linha de metrô e trem.

URL basehttps://api.trilhosagora.com.br/v1

Especificação OpenAPI 3.1/v1/openapi.json

FormatoJSON, UTF-8, horários de Brasília

AutenticaçãoCabeçalho X-API-Key

Limite60 requisições/min por chave

Sua chave da API

Cada chamada precisa de uma chave, gratuita para uso não comercial. Entre com o GitHub, gere uma chave por projeto e mande no cabeçalho X-API-Key. No painel você vê quanto cada chave usou e pode revogar quando quiser.

Gerar minha chave

Termos de uso

Uso não comercial é gratuito (projetos pessoais, estudos, pesquisa, sites e blogs sem fins lucrativos), desde que você mostre o crédito visível "Dados: TrilhosAgora" perto das informações. O link para o TrilhosAgora é bem-vindo, mas opcional, e pode usar rel="nofollow".

Uso comercial precisa de autorização: apps e produtos pagos, revenda dos dados, integração em serviços de empresas ou volume alto de requisições. Fale com a gente antes de usar.

Os dados vêm dos canais públicos das operadoras e podem ter atraso ou falhas; não use como única fonte em situações críticas. Respeite os limites de requisição: excessos recebem o erro 429; sem chave, o erro é 401.

Falar sobre uso comercial

Como os dados são atualizados

Três tempos diferentes aparecem na API. Eles não são a mesma coisa:

Frequência de coleta: a cada 30 segundos: De quanto em quanto tempo o TrilhosAgora consulta o canal público de cada operadora. Uma mudança publicada pela operadora entra no sistema em até 30 segundos.
Cache: alguns segundos: Para responder rápido e aguentar muitos acessos, a mesma resposta é reaproveitada por até 15 segundos e, enquanto uma nova é preparada, a anterior ainda pode ser servida por mais alguns segundos. Somando coleta e cache, o dado costuma ter menos de 1 minuto; no pior caso, cerca de 2 minutos.
atualizado_em: horário informado pela operadora: É o horário que a própria operadora coloca na situação da linha. Não indica quando o TrilhosAgora coletou: se a operadora não mexe no boletim, esse horário fica parado por horas, mesmo com a coleta funcionando normalmente.
desde: início da situação atual: Quando o TrilhosAgora viu a situação mudar para a atual. Se desde_confirmado for false, a linha não mudou desde o início do monitoramento e esse horário não representa uma mudança real.
fetched_at e stale: fetched_at é quando esta resposta foi montada a partir da coleta mais recente. Se a leitura falhar, a API repete a última resposta boa por até 2 minutos e marca stale: true; depois disso, responde com erro em vez de dados velhos.

Para mostrar "atualizado há X minutos" ao seu usuário, use fetched_at. Para mostrar o horário do boletim oficial, use atualizado_em.

Status

GET/v1/statusSituação atual de todas as linhas

Uma entrada por linha, na ordem de exibição do site. As operadoras são consultadas a cada 30 segundos e a resposta pode ser reaproveitada em cache por alguns segundos: normalmente o dado tem menos de 1 minuto. Veja "Como os dados são atualizados".

Limite: o da sua chave (60 requisições por minuto, por padrão).

Exemplo com curl

curl -H "X-API-Key: SUA_CHAVE" "https://api.trilhosagora.com.br/v1/status"

Resposta ao vivo

Exemplo de resposta

{
  "lines": [
    {
      "linha": 4,
      "nome": "Amarela",
      "rotulo": "Linha 4-Amarela",
      "slug": "4-amarela",
      "sigla": "4",
      "cor": "#ffd200",
      "status": "Operação Normal",
      "descricao": "",
      "operadora": "Motiva",
      "atualizado_em": "2026-10-28T09:45:05-03:00",
      "desde": "2026-10-28T04:41:57-03:00",
      "desde_confirmado": true
    }
  ],
  "fetched_at": "2026-10-28T12:45:20.000Z",
  "stale": false
}

Respostas

200 Situação das linhas.
429 Limite de requisições excedido.
503 Status temporariamente indisponível.

Histórico

GET/v1/historyOcorrências oficiais de uma linha nos últimos 7 dias

Situações fora da operação normal (velocidade reduzida, paralisação, atividade programada...), da mais recente para a mais antiga. "fim_em" nulo indica ocorrência em andamento.

Limite: o da sua chave (60 requisições por minuto, por padrão).

Parâmetro	Onde	Descrição	Valor
`line` obrigatório	query	Número da linha (Expresso Aeroporto: 100).

Exemplo com curl

curl -H "X-API-Key: SUA_CHAVE" "https://api.trilhosagora.com.br/v1/history?line=9"

Resposta ao vivo

Exemplo de resposta

{
  "events": [
    {
      "id": 57,
      "situacao": "Velocidade Reduzida",
      "descricao": "Devido a alagamento na região de Santo Amaro, circulação com velocidade reduzida.",
      "inicio_em": "2026-10-25T17:12:04-03:00",
      "fim_em": "2026-10-25T18:40:31-03:00",
      "atualizado_em": "2026-10-25T17:10:00-03:00"
    }
  ],
  "days": 7
}

Respostas

200 Ocorrências do período.
400 Linha inválida.
429 Limite de requisições excedido.

Estações

GET/v1/stationsEstações de uma linha

Estações na sequência cadastrada da linha. Cada estação tem página própria em /saopaulo/estacao/{slug}.

Parâmetro	Onde	Descrição	Valor
`line` obrigatório	query	Número da linha (Expresso Aeroporto: 100).

Exemplo com curl

curl -H "X-API-Key: SUA_CHAVE" "https://api.trilhosagora.com.br/v1/stations?line=4"

Resposta ao vivo

Exemplo de resposta

{
  "data": [
    {
      "name": "Luz"
    },
    {
      "name": "República"
    },
    {
      "name": "Higienópolis-Mackenzie"
    }
  ]
}

Respostas

200 Estações da linha.
400 Linha inválida.

Comunidade

GET/v1/reportsPossíveis anomalias relatadas por passageiros

Linhas em que vários passageiros relataram problema nos últimos minutos enquanto a operadora informa operação normal. Não é informação oficial.

Limite: o da sua chave (60 requisições por minuto, por padrão).

Exemplo com curl

curl -H "X-API-Key: SUA_CHAVE" "https://api.trilhosagora.com.br/v1/reports"

Resposta ao vivo

Exemplo de resposta

{
  "anomalies": [],
  "threshold": 3,
  "windowMinutes": 15
}

Respostas

200 Anomalias ativas.

Sem programar?

Para mostrar o status no seu site sem escrever código, use o widget de status do metrô para sites: é só copiar e colar, e dá para escolher as linhas, o tema e o tamanho.

Estatísticas de ocorrências De onde vêm os dados