Paragem.pt
Toda a informação de transportes de um território num sítio só, um código e
uma região por domínio. O Paragem.pt reúne os transportes que servem uma
região — os autocarros da concessão, os urbanos municipais, o transporte a
pedido, os comboios, as bicicletas partilhadas, os expressos e os táxis — e
devolve-os em formatos que qualquer um pode voltar a usar: páginas de paragem,
de linha e de concelho, um planeador de viagens, e os dados em GTFS e GBFS.
O princípio de desenho é uma só porta de entrada: quem viaja não precisa de
saber quem gere cada serviço. A navegação organiza-se por modo de transporte; a
entidade responsável aparece como informação secundária («Gerido por …»).
Uma região é uma autoridade de transportes — um município, uma comunidade
intermunicipal ou uma área metropolitana — e entra por configuração, sem um
único commit. O processo está em docs/NOVA-REGIAO.md.
Isto prova-se, não se promete
O CI constrói em todas as corridas três regiões inventadas de fio a pavio —
a Serra da Pedra Alta e o Baixo Sável, que são as provas, e as Terras do Ameno,
que são a demonstração. Não existem: nem uma paragem, nem uma estrada, nem um
horário vêm de sítio nenhum. É isso que lhes permite ser ao mesmo tempo a
demonstração pública do produto, sem pedir uma linha a ninguém, e a prova
executável do que o produto afirma.
São duas porque uma sozinha não prova nada sobre multi-região — não há com que
a comparar. E são diferentes uma da outra de propósito:
| Serra da Pedra Alta | Baixo Sável |
|---|
| artigo | «a Serra» | «o Baixo Sável» |
| autoridade | comunidade intermunicipal | município sozinho |
| concelhos | 2 | 1 |
| modos | autocarro, urbano municipal, bicicleta, táxi | autocarro |
Com dois artigos, nenhuma contração fica colada ao código. Com uma câmara
sozinha, fica provado que o produto não precisa de uma CIM. Com caixas
geográficas disjuntas, uma coordenada trocada entre regiões falha em vez de
cair nas duas. E com uma região de um modo só, vê-se que um modo ausente não
desenha uma secção vazia.
As provas são o dia zero, de propósito mínimas. As Terras do Ameno são o dia
100: a região que se mostra a quem decide, com os sete modos — a rede com
urbanos e interurbanos, o comboio com o autocarro à porta da estação, o
transporte a pedido com zonas e regra de reserva, o urbano de uma câmara, as
bicicletas, um expresso e os táxis — e um mapa desenhado por nós. Nasce, como
as outras, só com leitores genéricos; tudo o que ela tem sai de
data/manual/demo/inventar.py.
As regiões reais vivem noutra raiz
A compilação de dados de uma região — os percursos, o mapeamento das paragens,
os PDF das operadoras e das câmaras — não está aqui, e quase sempre não
pode estar: não é nossa para publicar enquanto a autoridade de transportes não
autorizar a reutilização.
Uma região vive numa raiz própria, que se aponta com PARAGEM_RAIZES:
PARAGEM_RAIZES=/caminho/para/os-dados uv run pipeline build --regiao <id>
Como isso funciona, e o que impõe, está em docs/RAIZES.md.
O estado, sem floreados
Há pipeline, há sítio e há planeador. O que não há, e é a razão de isto
ainda não estar publicado em nome de ninguém: os feeds não se republicam com
licença aberta enquanto a autoridade de transportes de cada região não
autorizar. É a Fase 5 do plano que está em CLAUDE.md.
O que uma construção produz, região a região:
| saída | o que é |
|---|
| GTFS da rede | reconstruído a partir do que a operadora publica |
| GTFS do operador ferroviário | tal e qual |
| GTFS dos expressos | recortado às viagens que servem a região |
| Recorte do OpenStreetMap | com margem, para as linhas que atravessam a fronteira |
| GBFS estático | os sistemas de bicicletas, sem prometer disponibilidade que não seja pública |
| GeoJSON | praças de táxi e traçados de urbanos municipais |
| Atribuição a concelhos | pela geometria da CAOP, e não por retângulo |
| Relatório de lacunas | o que falta, onde, e porque é que importa |
Para quem é
Três públicos, por esta ordem:
- Quem viaja. Um horário que se lê no telemóvel, à paragem, com pouca rede
e sem instalar nada. É para esta pessoa que as páginas são estáticas e
funcionam mesmo com o motor de viagens em baixo.
- Quem gere a rede — a autoridade de transportes e as câmaras. Passam a ter
o território inteiro numa vista só, e um sítio onde publicar avisos que chegam
a toda a gente ao mesmo tempo.
- Quem constrói outra coisa — quem quer os dados. Saem em GTFS e GBFS, os
formatos que o resto do mundo lê, com as licenças e as atribuições à vista.
E quem quer só ligar ao planeador — o «Como chegar» de um evento, de uma
câmara — faz uma ligação com a viagem no endereço:
docs/ENDERECOS.md.
Regras que não são de estilo
Estão inteiras no CLAUDE.md §4. As quatro que mais se notam:
- Só dados públicos e abertos, cada um registado em
data/sources.yaml com endereço, data, licença e a
atribuição que exige.
- Nunca inventar dados. O que falta fica explícito — no relatório de
lacunas e, na interface, com a data a que os horários se referem.
- Não raspar sítios que o proíbem. O que vem desses entra à mão, em
data/manual/, com a origem e a data anotadas.
- Acessibilidade WCAG 2.1 AA, que para uma autoridade de transportes não
é uma boa prática — é o Decreto-Lei n.º 83/2018.
Como se corre
Precisa de uv e de Python 3.11 ou mais recente.
uv run pipeline build --regiao prova --sem-rede # uma região inventada, em segundos
uv run pipeline build --regiao prova-municipio --sem-rede # a outra
uv run pipeline build --regiao demo --sem-rede # a demonstração, com os sete modos
uv run pipeline mosaicos --regiao demo # o mapa dela, desenhado da geografia
uv run pipeline build --regiao <id> # uma região real: descarrega, constrói, valida
uv run pipeline validate --regiao <id> # só o validador, sem reconstruir
uv run pipeline report --regiao <id> # o relatório de lacunas
uv run pytest
E as quatro verificações que o CI corre:
uv run pipeline check-proveniencia # sources.yaml × REUSE.toml × TERCEIROS.md
uv run pipeline check-regioes # duas ou mais regiões, zero fugas
uv run pipeline check-numeros # os números que cada região declara esperar
uv run pipeline check-bloqueios --todas # bloqueios novos vs os já aceites
Tudo o que sai vai para build/<regiao>/, que não está no Git: reconstrói-se
com o comando acima.
O parser de horários precisa do pdftotext (pacote poppler-utils), o recorte
do OpenStreetMap do osmium-tool, e o validador de GTFS de Java 17. As três
versões estão fixadas, e o porquê está em
docs/ARQUITETURA.md.
O que corre em tempo real, e vive à parte
O sítio serve páginas em cache, feitas do que o pipeline publica, e funciona
com tudo o resto em baixo. Duas coisas não cabem numa página guardada e
correm à parte:
otp/ — o motor de viagens, em Docker, atrás de um proxy com limites.disponibilidade/ — lê a página que um sistema de bicicletas publica e
serve as contagens como GBFS, com a hora da leitura. Corre como rota do
próprio sítio (web/src/app/api/station_status/route.js, um invólucro fino
sobre o mesmo núcleo) ou como contentor, à escolha de quem aloja. Ver
disponibilidade/README.md.
Sem eles o sítio funciona à mesma — mostra o que sabe e diz o que não sabe,
em vez de falhar em silêncio.
Licença
O software é AGPL-3.0-only. Cada ficheiro de dados que o sítio
publica diz os seus termos, e o rótulo sai do código (_termos, em
pipeline/src/paragem/sitio.py), e não de uma frase escrita à parte:
- ODbL, quando a receita da região o declara — o que deriva do
OpenStreetMap, com a atribuição dentro do próprio ficheiro;
- de terceiros, no ficheiro de outra entidade filtrado à região: os termos
são os dela;
- para consulta, no que construímos a partir de fontes sem licença aberta
declarada — publicá-lo com licença aberta é a Fase 5, depois de a autoridade
de transportes o autorizar;
- obra da casa, nas regiões de prova (sob a licença do código) e no
relatório da construção (CC BY 4.0).
Os termos de cada fonte estão registados um a um em data/sources.yaml.
A marca Paragem.pt não é coberta pela licença do código. Os pormenores
estão em AUTORIA.md; a declaração legível por máquina está em
REUSE.toml.
