🐝 Dados Abertos

Comprometidos em ser abertos

Estamos profundamente comprometidos com a transparência. A maior parte do código produzido no âmbito do desenvolvimento da Carris Metropolitana e do GO está publicado no Github. Agradecemos o teu feedback, comentários ou PRs! Também são regularmente publicados dados sobre a nossa operação rodoviária, o que inclui grandes números (ex. total de passageiros transportados) e outras informações mais detalhadas (ex. qualidade do serviço prestado para cada linha).

A maior parte destes números estão disponíveis livremente no API e podem ser consumidos em tempo real. Todas as rotas aqui documentadas são as mesmas que utilizamos para suportar as aplicações da TML, como o website e app da Carris Metropolitana e inúmeras ferramentas internas. Não aplicamos qualquer "tratamento especial" aos nossos APIs — todos têm acesso à mesma informação ao mesmo tempo, garantindo equidade e transparência na partilha dos dados.

Esta estratégia permite simplificar a nossa stack técnica e melhorar a qualidade dos sistemas para todos.

Existem claro determinados dados que requerem autenticação, pela sua natureza mais sensível ou impossibilidade técnica. Estamos disponíveis para avaliar cada caso, e para isso basta entrar em contacto connosco.

Projetos que gostamos 💛

Estes são alguns dos projetos que utilizam os nossos dados abertos e que achamos extremamente interessantes!

Versões

Todos os endpoints públicos do GO são versionados pois destinam-se a consumo externo, permitindo o desenvolvimento de novas funcionalidades sem comprometer a compatibilidade com sistemas que dependem das estruturas de dados de versões anteriores.

Uma vez que todas as respostas são JSON, adicionar novas propriedades aos endpoints não é considerado uma alteração significativa, pois estas propriedades podem ser ignoradas com segurança pelos consumidores. Portanto, nesses casos, a versão pode não ser alterada. Esta abordagem parece-nos equilibrada pois permite-nos introduzir melhorias mais rapidamente enquanto minimizamos o impacto nas integrações existentes.

Os restantes endpoints autenticados do GO não são versionados. Esta é uma decisão controversa que tomámos para permitir maior agilidade no desenvolvimento dos sistemas. A grande maioria dos endpoints requer autenticação e é utilizada apenas para a própria aplicação de frontend. A estrutura em monorepo, preview environments, deploys automáticos, kubernetes, e a própria natureza web do projeto, permite-nos manter o frontend e o backend sincronizados e atualizados.

Estrutura uniforme da resposta

Todas as respostas do API seguem a mesma estrutura padronizada, que garante a consistência em todos os endpoints e fornece uma framework para incluir informações adicionais de debugging quando necessário.

Em caso de erros, este formato oferece uma forma clara e estruturada para descrever o que correu mal e, quando possível, como o problema poderá ser resolvido.

{
	status: "success",
	timestamp: 1721023200,
	message: null,
	data: [ ... ] or { ... } // The requested data
}

{
	status: "error",
	timestamp: 1721023200,
	message: "Unable to communicate with database",
	data: null
}

TypeScript

A utilização de uma linguagem tipificada é fortemente recomendada. Para utilizadores de Typescript, fornecemos um pacote no NPM com tipos para todas as estruturas utilizadas. Decidimos utilizar Calendar Versioning para este pacote, pelo que apenas garantimos compatibilidade com a versão mais recente do API.

Endpoints disponíveis

O GO tem um módulo dedicado aos dados abertos, chamado hub, com o objetivo de facilitar o acesso à informação da rede de transportes. O objetivo é ir adicionando mais endpoints públicos, sempre que possível, para cumprir a nossa promessa de transparência.

Uma vez que o GO toca em vários temas de uma operação de transportes, e que está desenvolvido por módulos, agrupámos os endpoints para estruturar a informação que cada um disponibiliza. Podes utilizar qualquer um destes endpoints diretamente nos teus frontends sem te preocupares com limites ou muitos utilizadores. Temos políticas de cache agressivas que permitem responder rapidamente a um elevado número de clientes, mas pedimos respeito e bom senso para que todos possam usufruir de um API estável.

URL base: https://go.tmlmobilidade.pt/hub/api/:version/:path

Alertas

Com estes endpoints consegues ir buscar informação de desvios, supressões, alterações de oferta, novos horários, etc. que os vários operadores de transporte publicam ao público. Em muitos casos, são estes endpoints que são disponibilizados às aplicações de planeamento, como Google Maps, Transit, CityMapper, etc.

Planos

Se precisas de aceder ao histórico da oferta de todos os operadores, então encontraste os endpoints que procuras. Dependendo do operador tens mais ou menos histórico, mas no geral quase todos estão disponíveis desde o início de 2026. Para a CM tens desde 1 Jan 2024. O formato de publicação desta informação é através de ficheiros GTFS, que é o standard internacional para comunicar informação planeada para uma rede de transportes. Consegues também fazer o download de um GTFS unificado para todos os operadores de transporte, que é essencialmente uma agregação dos planos de operação que estão ativos num determinado momento.

Rede de Transportes

Informação da rede de transportes em JSON. Muito útil para construir aplicações sem ser necessário um grande investimento em servidores ou código para o processamento de ficheiros GTFS. Estes endpoints são também utilizados nos suportes de informação ao público do navegante®.

Tempo Real

Informação em tempo real da rede de transportes, como posições de veículos e estimativas de chegada. O estimador de horários ainda está em fase experimental, pelo que deve ser utilizado com algum cuidado.

Localizações

Listas de limites geográficos, como distritos, municípios, localidades, etc. úteis para situar administrativamente e de forma automática coordenadas geográficas. Os IDs de cada feature seguem a nomenclatura DICOFRE (Distrito, Concelho, Freguesia)

Debug

Endpoints para debugging do sistema. Uma vez que utilizamos estes endpoints nos suportes de informação ao público, como o site e app da Carris Metropolitana e app navegante®, é importante garantir que o sistema está online e a funcionar.