Rede de Transportes
Explora como utilizar o API para construir aplicações de planeamento de viagens.
Nestes endpoints são disponibilizados os dados de oferta de transporte, em JSON, para todos os operadores que estão incluídos na exportação do GTFS global.
O sistema que converte os dados para JSON tem por base o mesmo GTFS que é disponibilizado ao público, incluindo às aplicações de planeamento de viagens como o Transit, Citymapper, Moovit, Google Maps, Apple Maps, entre outros. É possível construir aplicações de planeamento sem ser necessário investimento em servidores ou código complexo para o processamento de ficheiros GTFS.
Estes endpoints são utilizados nos suportes de informação da TML, como o site da Carris Metropolitana, a app navegante®, os painéis nas paragens (PIPs), MUPIs, etc. Fazemos questão de utilizar a mesma base para garantir que a informação é consistente e de qualidade independentemente de onde os passageiros a prefiram consultar.
A utilização da informação disponibilizada nestes endpoints é livre e não requer nenhum pedido de permissão antecipado, estando sujeita apenas ao bom senso em termos de carga nos sistemas. Mesmo assim, estamos sempre curiosos para conhecer novos projetos que utilizam os nossos dados.
Organização da Rede
As redes de transporte público no mundo estão organizadas, na sua maioria, na lógica de linhas, rotas e percursos. Uma linha pode ter inúmeras rotas (também chamadas de base e variantes) e uma rota pode ter, no máximo, dois percursos (o de ida e o de volta).
A linha define a intenção do serviço, enquanto que cada percuso define o caminho exato que será percorrido pelo veículo, e a sequência de paragens que serão servidas em determinados horários.
Um exemplo é a linha Amarela do Metro de Lisboa. Esta linha tem duas rotas e cada rota tem dois sentidos:
- A. Linha Amarela
line- A.1. Rato - Odivelas
route- A.1.1. Rato - Odivelas
pattern - A.1.2. Odivelas - Rato
pattern
- A.1.1. Rato - Odivelas
- A.2. Rato - Campo Grande
route- A.2.1. Rato - Campo Grande
pattern - A.2.2. Campo Grande - Rato
pattern
- A.2.1. Rato - Campo Grande
- A.1. Rato - Odivelas
- B. Linha Vermelha
line- etc...
Cada um destes sentidos é um percurso, ou pattern, e é a este nível que são definidos os horários e os caminhos dos veículos (shapes, path e trips).
Por este motivo, decidimos formalizar esta hierarquia no API para que fique totalmente adaptado à forma como os passageiros esperam consultar a informação. Estes conceitos são quase universais, fundamentais ao planeamento das redes, e aplicáveis aos suportes de informação digitais e físicos. Consideramos que as exceções encontradas a esta lógica devem ser tratadas como erros a ser corrigidos, pois vão contra as expetativas dos passageiros.
Linhas, Rotas e Percursos
Linhas
No Hub, uma linha é representada por um objeto JSON com as seguintes propriedades:
| Propriedade | Tipo | Descrição |
|---|---|---|
_id | String | ID único da linha. |
agency_id | String | ID único do operador ao qual a linha pertence. |
color | HexColor (String) | Cor da linha, em formato hexadecimal, com o prefixo #. |
text_color | String | Cor do texto da linha, em formato hexadecimal, com o prefixo #. |
short_name | String | Identificador principal da linha para os passageiros. |
long_name | String | Nome da linha, que normalmente é a origem-destino da rota base ou um resumo do serviço efetuado (ex: Circular). |
tts_name | String | Nome da linha adaptado para leitores de ecrã. |
pattern_ids | Array<String> | IDs dos percursos que pertencem a esta linha. |
route_ids | Array<String> | IDs das rotas que pertencem a esta linha. |
stop_ids | Array<String> | IDs das paragens que pertencem a esta linha. |
district_ids | Array<String> | IDs de todos os distritos por onde todos os percursos desta linha passam (códigos DICOFRE). |
district_names | Array<String> | Nomes dos distritos por onde todos os percursos desta linha passam (CAOP). |
municipality_ids | Array<String> | IDs de todos os municípios por onde todos os percursos desta linha passam. |
municipality_names | Array<String> | Nomes dos municípios por onde todos os percursos desta linha passam. |
parish_ids | Array<String> | IDs de todas as freguesias por onde todos os percursos desta linha passam. |
parish_names | Array<String> | Nomes das freguesias por onde todos os percursos desta linha passam. |
locality_ids | Array<String> | IDs de todas as localidades por onde todos os percursos desta linha passam. |
locality_names | Array<String> | Nomes das localidades por onde todos os percursos desta linha passam. |
facilities | Array<String> | Instalações de utilidade pública que esta linha serve (Escolas, Hospitais, etc.). Em desenvolvimento. |
Rotas
No Hub, uma rota é descendente de uma linha e é representada por um objeto JSON com as seguintes propriedades:
| Propriedade | Tipo | Descrição |
|---|---|---|
_id | String | ID único da rota. |
agency_id | String | ID único do operador ao qual a rota pertence. |
color | HexColor (String) | Cor da rota, em formato hexadecimal, com o prefixo #. |
text_color | String | Cor do texto da rota, em formato hexadecimal, com o prefixo #. |
short_name | String | Identificador principal da rota para os passageiros. |
long_name | String | Nome da rota, que normalmente é a origem-destino ou um resumo do serviço efetuado (ex: Circular). |
tts_name | String | Nome da rota adaptado para leitores de ecrã. |
line_id | String | ID da linha a que a rota pertence. |
pattern_ids | Array<String> | IDs dos percursos que pertencem a esta rota. |
stop_ids | Array<String> | IDs das paragens que pertencem a esta rota. |
district_ids | Array<String> | IDs de todos os distritos por onde todos os percursos desta rota passam (códigos DICOFRE). |
district_names | Array<String> | Nomes dos distritos por onde todos os percursos desta rota passam (CAOP). |
municipality_ids | Array<String> | IDs de todos os municípios por onde todos os percursos desta rota passam. |
municipality_names | Array<String> | Nomes dos municípios por onde todos os percursos desta rota passam. |
parish_ids | Array<String> | IDs de todas as freguesias por onde todos os percursos desta rota passam. |
parish_names | Array<String> | Nomes das freguesias por onde todos os percursos desta rota passam. |
locality_ids | Array<String> | IDs de todas as localidades por onde todos os percursos desta rota passam. |
locality_names | Array<String> | Nomes das localidades por onde todos os percursos desta rota passam. |
facilities | Array<String> | Instalações de utilidade pública que esta rota serve (Escolas, Hospitais, etc.). Em desenvolvimento. |
Percursos
No Hub, um percurso (ou pattern) é descendente de uma rota e contém a informação relevante sobre o serviço de transporte disponibilizado.
Para ser possível apresentar alterações antecipadas, e manter o serviço atual, o endpoint dos patterns retorna uma lista. Enquanto que o ID do percurso é único,
podem existir várias versões do mesmo percurso, identificadas pela propriedade version e com uma determinada validade temporal.
Pattern Version
Um percurso é representado por um objeto JSON com as seguintes propriedades:
| Propriedade | Tipo | Descrição |
|---|---|---|
_id | String | ID único do percurso. |
agency_id | String | ID único do operador ao qual o percurso pertence. |
version_id | String | Hash do conteúdo do percurso que identifica a sua versão, válida num determinado período temporal. |
valid_on | Array<OperationalDate> (Array<Integer>) | Datas de validade da versão do percurso. |
color | HexColor (String) | Cor do percurso, em formato hexadecimal, com o prefixo #. |
text_color | HexColor (String) | Cor do texto do percurso, em formato hexadecimal, com o prefixo #. |
short_name | String | Identificador principal do percurso para os passageiros. |
headsign | String | Destino do percurso para os passageiros. Também conhecido como Bandeira. |
tts_headsign | String | Nome do percurso adaptado para leitores de ecrã. |
direction_id | GtfsTripDirection (String) | Indica se o percurso é de ida 0 ou de volta 1. |
line_id | String | ID da linha a que o percurso pertence. |
route_id | String | ID da rota a que o percurso pertence. |
shape_id | String | ID do caminho do percurso |
shape_extension | NonNegativeInteger (Integer) | Extensão do percurso, em metros. |
shape_polyline | EncodedPolyline (String) | Google Encoded Polyline do caminho do percurso. Podes utilizar o nosso pacote @tmlmobilidade/go-utils-geo para descodificar o conteúdo para GeoJSON. |
path | Array<HubV1ApiPatternWaypointSchema> | Sequência de paragens servidas por esta versão do percurso. |
trips | Array<HubV1ApiPatternTripSchema> | Horários de passagem em todas as paragens desta versão do percurso. |
district_ids | Array<String> | IDs de todos os distritos por onde o percurso passa (códigos DICOFRE). |
district_names | Array<String> | Nomes dos distritos por onde o percurso passa (CAOP). |
municipality_ids | Array<String> | IDs de todos os municípios por onde o percurso passa. |
municipality_names | Array<String> | Nomes dos municípios por onde o percurso passa. |
parish_ids | Array<String> | IDs de todas as freguesias por onde o percurso passa. |
parish_names | Array<String> | Nomes das freguesias por onde o percurso passa. |
locality_ids | Array<String> | IDs de todas as localidades por onde o percurso passa. |
locality_names | Array<String> | Nomes das localidades por onde o percurso passa. |
facilities | Array<String> | Instalações de utilidade pública que o percurso serve (Escolas, Hospitais, etc.). Em desenvolvimento. |
Pattern Waypoint
Um waypoint representa um ponto de recolha e/ou largada de passageiros no percurso.
A chave primária deve ser a combinação das propriedades stop_id e stop_sequence pois uma paragem pode ser servida mais do que uma vez na mesma viagem (ex: percursos circulares).
Um waypoint é representado por um objeto JSON com as seguintes propriedades:
| Propriedade | Tipo | Descrição |
|---|---|---|
stop_id | String | ID da paragem servida. |
stop_sequence | String | Índice de sequência da paragem no percurso. |
allow_pickup | Boolean | Indica se são permitidas entradas nesta paragem. |
allow_drop_off | Boolean | Indica se são permitidas saídas nesta paragem. |
distance | NonNegativeInteger (Integer) | Distância acumulada desde o início do percurso. |
distance_delta | NonNegativeInteger (Integer) | Distância entre esta e a paragem anterior. |
Pattern Trip
O GTFS é bastante flexível para conseguir responder a inúmeras necessidades de diferentes operações de transporte público, com a consequência de provocar uma enorme duplicação de informação, especialmente no ficheiro stop_times.txt.
No GO Hub, com o objetivo de aumentar a eficiência do API, combinamos viagens iguais no mesmo objeto, identificando-as não pelo trip_id do GTFS mas sim por um hash do seu conteúdo. Para que não se perca a correspondência com o GTFS, disponibilizamos a propriedade trip_ids. O trade-off é que para um determinado dia, apenas com a informação do API dos percursos, não é possível saber qual o trip_id exato que será executado. Aceitamos esta característica pois o necessário é ligar a informação em tempo real à informação planeada, e não o contrário.
Uma trip é representada por um objeto JSON com as seguintes propriedades:
| Propriedade | Tipo | Descrição |
|---|---|---|
version_id | String | Hash do conteúdo da viagem que identifica a sua versão, válida num determinado período temporal. |
valid_on | Array<OperationalDate> (Array<Integer>) | Datas em que esta viagem se irá realizar. |
trip_ids | Array<String> | IDs originais do GTFS de viagens iguais (mesmos horários e mesmo percurso, mas dias diferentes). |
service_ids | Array<String> | IDs originais dos calendários do GTFS associados aos trip_ids desta viagem. |
schedule | Array<ScheduledArrival> | Horários de passagem em todas as paragens desta viagem. |
Schedule Arrival
Uma arrival é representado por um objeto JSON com as seguintes propriedades:
| Propriedade | Tipo | Descrição |
|---|---|---|
stop_id | String | ID da paragem servida. |
stop_sequence | String | Índice de sequência da paragem no percurso. |
arrival_time | String | Horário de chegada à paragem no formato operacional (24h+). |
arrival_time_24h | String | Horário de chegada à paragem, em formato 24h. |
Endpoints disponíveis
| Path | Descrição |
|---|---|
/v1/network/lines | Todas as linhas de todos os operadores em operação num determinado momento. |
/v1/network/patterns/:id | Todas as linhas de todos os operadores em operação num determinado momento. |
/v1/network/stops | Todas as paragens de todos os operadores. Este endpoint pode devolver paragens de zonas que não são da AML. |
/v1/network/stops/:id | Detalhe de uma paragem específica, com informação adicional. |
/v1/network/stops.csv | Todas as paragens no formato .csv (semelhante ao ficheiro stops.txt do GTFS). |