Export Data

Esta aplicação é a ferramenta oficial de exportação de dados da Transportes Metropolitanos de Lisboa. Permite que utilizadores autorizados extraiam dados operacionais e analíticos da plataforma GO e os guardem em ficheiros CSV para relatórios, análise ou utilização noutros sistemas.

O acesso é controlado através de uma chave de acesso que é introduzida ao iniciar a ferramenta.

Requisitos

É necessário ter instalado o Node.js no computador.

Como usar a ferramenta

1. Abrir a linha de comandos

• Windows: Abrir o PowerShell
• Mac: Abrir o Terminal

2. Executar a ferramenta

Escrever o seguinte comando e pressionar Enter:

npx @tmlmobilidade/export-data

3. Instalar a ferramenta (apenas na primeira vez)

Se for a primeira vez que usa a ferramenta, aparecerá uma mensagem a pedir confirmação para instalar. Escrever y e pressionar Enter:

Need to install the following packages:
@tmlmobilidade/export-data@20260213.1500.47
Ok to proceed? (y) y

4. Introduzir a chave de acesso (apenas na primeira vez)

Na primeira utilização, será pedida a chave de acesso. Esta fica guardada no sistema e não será necessário voltar a introduzi-la:

◆  Por favor introduz a chave de acesso:
│  Chave de acesso...

5. Identificar a exportação

A ferramenta mostra informações importantes sobre a exportação:

┌  Bem-vindo ao exportador de dados da CM!
│
●  A versão da aplicação é: 20260213.1500.47
│
●  O ID desta exportação é: 7DTHDZ
│
●  Todos os resultados serão guardados aqui: /Users/{nome}/export-7DTHDZ
│
◇  Chave de acesso encontrada no armazenamento seguro do sistema.

Nota: O caminho mostrado é onde os ficheiros exportados serão guardados.

6. Escolher o tipo de dados a exportar

Use as setas do teclado para navegar, a barra de espaços para selecionar e Enter para confirmar:

◆  Escolhe os dados que queres exportar:
│  ◻ 1. Validações APEX
│  │ ◻ 1.0. Validações em bruto
│  └ ◻ 1.1. Validações agregadas (escolher campos)
│  ◻ 2. Rides
│  └ ◻ 2.0. Rides em bruto (SLAs)
│  ◻ 3. Vehicle Events
│  └ ◻ 3.0. Vehicle Events em bruto
│  ◻ 4. HashedShapes
│  └ ◻ 4.0. HashedShapes para GeoJSON
│  ◻ 5. SAMs
│  └ ◻ 5.0. SAMs em bruto (Sequencialidade)
└

Tipos de dados disponíveis

1. Validações APEX

Dados sobre validações de títulos de transporte.

• Validações em bruto
  Cada validação individual (cada vez que um passageiro valida um passe). Gera ficheiros grandes com todos os detalhes.

• Validações agregadas
  Dados de validação resumidos por data e dimensões escolhidas (linha, paragem, veículo, operador, viagem, tipo de título). Ideal para relatórios e análise sem ficheiros volumosos.

2. Rides

• Rides em bruto
  Dados completos de viagens/serviço. Útil para análise de SLAs e desempenho operacional.

3. Eventos de veículos

• Eventos de veículos em bruto
  Eventos registados pelos veículos (passagens em paragens, etc.). Útil para análise operacional detalhada.

4. HashedShapes

• HashedShapes para GeoJSON
  Traçados geográficos de percursos exportados como GeoJSON. Útil para visualização em mapas ou ferramentas GIS. Requer especificar os IDs das formas a exportar.

5. SAMs

• SAMs em bruto
  Dados de Sequencialidade: informação sobre sequências de transações (esperadas vs encontradas vs em falta). Útil para análise de consistência, tipicamente por operador.

Exemplo prático: Exportar validações agregadas

Este exemplo mostra como exportar validações agregadas por linha, tipo de passe e paragem, para as linhas 1001 e 4701, em paragens específicas, durante dois dias.

Passo 1: Selecionar o tipo de exportação

Usar a barra de espaços para marcar "1.1. Validações agregadas":

◆  Escolhe os dados que queres exportar:
│  ◻ 1. Validações APEX
│  │ ◻ 1.0. Validações em bruto
│  └ ◼ 1.1. Validações agregadas (escolher campos)

Pressionar Enter para confirmar.

Passo 2: Escolher as dimensões de agregação

Selecionar as colunas que pretende no ficheiro final. A data é sempre incluída automaticamente.

Neste exemplo, vamos selecionar:

• Linha (line_id)
• Tipo de passe (product_id)
• Paragem (stop_id)

◆  Escolhe os campos para agrupar as validações (a data é sempre incluída):
│  ◼ Linha (line_id)
│  ◻ Pattern (pattern_id)
│  ◼ Tipo de passe (product_id)
│  ◻ Viagem (trip_id)
│  ◼ Paragem (stop_id)
│  ◻ Operador (agency_id)
│  ◻ Veículo (vehicle_id)
└

Pressionar Enter para confirmar.

Passo 3: Escolher os filtros

Selecionar que filtros aplicar aos dados:

◆  Escolhe os filtros que queres aplicar:
│  ◻ Operador (agency_id)
│  ◼ Paragem (stop_id)
│  ◼ Linha (line_id)
│  ◻ Pattern (pattern_id)
│  ◻ Veículo (vehicle_id)
└

Neste exemplo, vamos filtrar por Linha e por Paragem.

Passo 4: Filtrar por linha

Introduzir os IDs das linhas separados por vírgulas. Neste exemplo: 1001,4701

◇
│  FILTRAR POR LINE ID:
│    • Introduz os Line IDs separados por vírgulas. Exemplo: 1001,1002,etc...
│    • Se não introduzires nenhum Line ID, este filtro não será aplicado.
│
◆  Line IDs:
│  1001,4701
└

Passo 5: Filtrar por paragem

Introduzir os IDs das paragens separados por vírgulas. Não esquecer o zero à esquerda.

Neste exemplo: 030009,030021,060001,090099

◇
│  FILTRAR POR STOP ID:
│    • Introduz os Stop IDs separados por vírgulas. Exemplo: 010101,020202,etc...
│    • Não te esqueças do zero à esquerda.
│    • Se não introduzires nenhum Stop ID, este filtro não será aplicado.
│
◆  Stop IDs:
│  030009,030021,060001,090099
└

Passo 6: Filtrar por data (obrigatório)

Introduzir a data de início e de fim no formato YYYYMMDD ou YYYY-MM-DD.

Importante:

• Filtrar por datas é obrigatório
• A data de início não pode ser anterior a 1 de janeiro de 2024 (20240101)

Neste exemplo: de 16 de março de 2025 até 17 de março de 2025

◇
│ • Introduz as datas operacionais no formato ano-mês-dia
│   Exemplo: 20250101 ou 2025-01-01
│ • Devido ao enorme volume de dados, filtrar por datas é obrigatório.
│ • A data de início não pode ser anterior a 1 Jan. 2024 (20240101).
│
◆  Data de Início:
│  20250316
│
◆  Data de Fim:
│  20250317
└

Passo 7: Aguardar e localizar o ficheiro

A exportação será executada e o ficheiro será guardado no local indicado no início.

Localização do ficheiro:
/Users/{nome-de-utilizador}/export-7DTHDZ/validations-by-line_id-product_id-stop_id-20250316-20250317.csv

Exemplo do conteúdo do ficheiro:

Dicas úteis

• Navegação: Use as setas do teclado para navegar entre opções
• Seleção: Use a barra de espaços para selecionar/desselecionar
• Confirmação: Use Enter para confirmar e avançar
• IDs de paragens: Não esquecer o zero à esquerda (exemplo: 030009 em vez de 30009)
• Datas: Podem ser escritas como 20250316 ou 2025-03-16
• Ficheiros: Todos os ficheiros da mesma exportação ficam na mesma pasta, identificada pelo ID da exportação

Resolução de problemas

A ferramenta não inicia

Verificar se o Node.js está instalado: executar node --version na linha de comandos

Erro de chave de acesso

Contactar o administrador para obter uma nova chave de acesso

Não encontro os ficheiros exportados

O caminho completo é mostrado no início da exportação. Procurar pela pasta export-{ID}