Alertas
Descobre o que é um alerta de serviço de uma operação de transportes públicos.
Os Alertas de Serviço são mensagens que os operadores de transporte disponibilizam ao público para informar de alterações programadas, desvios inesperados, cancelamentos, atrasos, etc. São fundamentais para garantir que os utilizadores de transporte se possam organizar com antecedência ou encontrar alternativas em caso de imprevistos pontuais.
Os alertas referenciam objetos da rede de transporte, como paragens, linhas ou viagens, afetando-as com uma causa e um efeito. No GO Hub seguimos a especificação do GTFS-RT Service Alerts para tipificar um alerta. Adicionalmente, o GO Hub disponibiliza propriedades que podem ser úteis para tornar a informação mais intuitiva e legível.
Estrutura de um alerta
O tipo HubV1ApiAlert representa cada alerta. No Hub, um alerta é representado por um objeto JSON com as seguintes propriedades:
| Propriedade | Tipo | Descrição |
|---|---|---|
_id | String | ID único do alerta. |
agency_id | String | ID único do operador associado ao alerta. |
title | String | Título do alerta. |
description | String | Descrição do alerta. |
cause | GtfsRtCause (String) | Causa do alerta, por exemplo ACCIDENT, CONSTRUCTION, OTHER_CAUSE ou WEATHER. |
effect | GtfsRtEffect (String) | Efeito do alerta, por exemplo DETOUR, NO_SERVICE, SIGNIFICANT_DELAYS ou STOP_MOVED. |
coordinates | [Latitude, Longitude] | null | Coordenadas do alerta. |
active_period_start_date | UnixMilliseconds (Integer) | Data de início do período de atividade do alerta (inclusive). |
active_period_end_date | UnixMilliseconds (Integer) ou null | Data de fim do período de atividade do alerta (inclusive). |
image_url | String ou null | URL da imagem do alerta. |
info_url | URL (String), string vazia ou null | URL da informação do alerta. |
municipality_ids | Array<String> | IDs dos municípios associados ao alerta. |
reference_type | AlertReferenceType (String) | agency, lines, stops ou rides. |
references | Array<AlertReference> | Referências com parent_id (String) e child_ids (Array<String>). |
export const HubV1ApiAlertSchema = z.object({
_id: z.string(),
active_period_end_date: UnixMillisecondsSchema.nullable().default(null),
active_period_start_date: UnixMillisecondsSchema,
agency_id: z.string(),
cause: GtfsRtCauseSchema,
coordinates: z.tuple([z.number(), z.number()]).nullable().default(null),
description: z.string(),
effect: GtfsRtEffectSchema,
image_url: z.string().nullable().default(null),
info_url: z.union([z.string().url(), z.literal('')]).nullable().default(null),
municipality_ids: z.array(z.string()).default([]),
reference_type: AlertReferenceTypeSchema,
references: z.array(AlertReferenceSchema).default([]),
title: z.string(),
});active_period_end_date: null indica que não foi definida uma data de fim. coordinates, image_url e info_url também podem ser null; info_url pode ainda ser uma string vazia. cause e effect usam os valores definidos pelo GTFS-RT. municipality_ids e references podem ser listas vazias.
Endpoints disponíveis
Base path: https://go.tmlmobilidade.pt/hub/api
| Método | Path | Tipo de resposta | Descrição |
|---|---|---|---|
| GET | /v1/:organizationId/alerts | HubV1ApiAlert[] em data | Alertas publicados pelos operadores da organização, em JSON. |
| GET | /v1/:organizationId/alerts.rss | RSS | Alertas combinados num canal da organização. |
| GET | /v1/:organizationId/alerts/gtfs | Feed GTFS-RT em data | Service Alerts em JSON. |
| GET | /v1/:organizationId/alerts/gtfs.pb | Protobuf | Service Alerts em formato binário. |
Obtém :organizationId na lista de organizações. Uma organização inexistente ou sem dados abertos devolve HTTP 404.
As respostas de sucesso usam HTTP 200. O JSON simplificado e o RSS têm cache pública de 30 segundos; os feeds GTFS-RT têm cache de 3 segundos. As respostas JSON usam o formato comum do Hub. O RSS é devolvido diretamente com Content-Type: application/rss+xml; charset=utf-8, e o Protobuf com Content-Type: application/octet-stream.
Os feeds GTFS-RT JSON usam FeedMessage: header contém gtfs_realtime_version, feed_version (String ou null, opcional), incrementality (FULL_DATASET) e timestamp (UnixSeconds); entity contém entidades com id e, conforme o feed, alert, trip_update ou vehicle. O endpoint .pb devolve a mesma estrutura em Protobuf. Sem alertas publicados, o JSON simplificado devolve data: []. Os feeds GTFS-RT seguem as regras de combinação por organização.