Introdução

O que é um GTFS?

GTFS significa General Transit Feed Specification. É um standard internacional que define como aplicações de planeamento (ex. Google Maps, Transit, CityMapper) devem interpretar redes de transportes públicos, como horários e percursos. A especificação foi criada pelo Google, mas é agora mantida e orientada pela equipa da Mobility Data, de forma aberta e partilhada.

O standard define dois grupos: o GTFS Schedule, onde estão mapeadas todas as paragens, percursos e horários planeados para um determinado operador; e o GTFS Realtime, que funciona como uma camada em cima do GTFS Schedule para ajustar as informações à realidade do momento (ex. horários mudam pois houve um acidente na ponte).

O GTFS Schedule não é mais do que uma série de tabelas (ex. ficheiros Excel) agrupados num arquivo .zip. Cada uma destas tabelas é um ficheiro separado por vírgulas (.csv que significa comma-separated values) mas a terminação dos ficheiros é sempre .txt para evitar conflitos com alguns programas. Cada ficheiro tem um nome específico e um conjunto obrigatório de colunas, formando uma estrutura relacional.

O GTFS Realtime é um pouco mais complexo pois utiliza o formato Protobuf, o que exige necessariamente aplicações adicionais ou scripts de descodificação. Não deixa de ser apenas um "ficheiro" que contém alterações ou informações adicionais ao que estava descrito no GTFS planeado. Protobuf é um formato também desenvolvido pelo Google que pretende ser extremamente eficiente na transmissão de dados entre aplicações.

Quem produz o GTFS são os operadores de transporte público, e quase todos têm pelo menos a versão planeada.

Exemplo de ficheiro GTFS

Disponibilizamos um GTFS de exemplo simplificado para a Linha Amarela do Metro de Lisboa, apenas com as colunas necessárias e 4 horários. Explora as relações entre os ficheiros para compreender a lógica subjacente ao standard GTFS.

Descarregar GTFS de Exemplo // TODO

Como posso abrir/ler um GTFS?

Podes descompactar o arquivo GTFS e abrir cada ficheiro em ferramentas como o Microsoft Excel ou o Google Sheets. Pode ser necessário alterar a extensão de cada ficheiro de .txt para .csv.

Alguns destes ficheiros podem ser demasiado grandes, o que pode exceder os limites destes programas. Nestes casos, é melhor utilizar ferramentas automatizadas concebidas para lidar com dados GTFS. Embora os ficheiros GTFS sejam legíveis por humanos, destinam-se ao processamento por sistemas automatizados para gerir e manipular eficientemente os dados neles armazenados.

GTFS v30

Como o GTFS foi inicialmente pensado apenas para comunicar horários e percursos às aplicações de planeamento, existem algumas informações que a TML considera essenciais que não estão mapeadas no standard. Ainda, o GTFS permite mapear informações de diferentes formas tornando mais complexo o seu entendimento e processamento.

A TML utiliza o GTFS como formato standard para comunicar as operações de transporte com os operadores e com o público. Tal como acontece com várias autoridades de transporte no mundo, a TML decidiu expandir o standard para que os ficheiros GTFS possam incluir informações adicionais que são essenciais para configurar outros sistemas, como o sistema de bilhética APEX. Ao longo do tempo, esta extensão tem evoluído para responder ao feedback dos operadores e às evoluções tecnológicas dos sistemas de informação ao público e de bilhética.

Atualmente, estamos na versão 30 desta extensão. Esta atualização, introduzida em Setembro de 2026, define uma estrutura comum para todos os operadores de transporte sem acrescentar nenhuma coluna obrigatória adicional às que já estão presentes no standard. No entanto, para garantir a consistência da informação e simplificar o processo de configuração da APEX, a TML exige que algumas colunas que já existem no standard sejam obrigatoriamente preenchidas.

A motivação desta atualização é a simplificação das exigências, reduzindo a duplicação de informação e a necessidade de desenvolvimentos para produzir um ficheiro GTFS adaptado às necessidades específicas da TML.

Para a identificação da linha, o campo route_short_name, que é opcional no standard, é considerado obrigatório no GTFS v30. O seu valor é mapeado para o campo lineLongID na APEX. Desta forma, os campos adicionais line_id, line_short_name e line_long_name do GTFS deixam de ser necessários. Os operadores podem continuar a enviar o ficheiro routes.txt com estes campos pois serão corretamente ignorados pelos sistemas.

Para a identificação do percurso, num número significativo de operadores, o campo shape_id do ficheiro trips.txt já é igual ao campo pattern_id. Por esse motivo deixa de ser necessário enviar este campo, uma vez que são essencialmente colunas duplicadas. Assim, o campo shape_id, que já era um requisito, passa a ser utilizado como identificador do percurso e é mapeado diretamente para o patternLongID na APEX. O mesmo shape_id deve ser utilizado de forma consistente em trips.txt e shapes.txt, garantindo a correspondência entre as viagens e a geometria do percurso. Numa fase de transição, é importante que o valor do shape_id seja igual ao pattern_id para que não exista perda de informação.

É recomendado que o shape_id seja definido através da combinação do route_id com o direction_id:

shape_id = route_id + direction_id

Desta forma, a versão 30 implementa uma estrutura comum baseada no GTFS Standard, sem necessidade de campos adicionais como line_id ou pattern_id. A informação necessária à APEX é obtida através dos campos standard e das regras de utilização definidas para o GTFS versão 30.

Ferramentas úteis

Uma breve coleção de ferramentas que utilizamos diariamente para validar e inspecionar dados em GTFS: