#AutoTranslate
Descrizione breve
I dati relativi alla formazione sono informazioni sui carri (e locomotive) di un treno, inclusa la composizione di un treno. I dati relativi alla formazione comprendono non solo la posizione dei singoli veicoli in un treno, ma anche le caratteristiche dei singoli veicoli.
Dall’autunno 2024 offriamo un’API REST che fornisce, come struttura dati JSON, i dati sulla formazione di un treno per un determinato numero del treno in un determinato giorno di esercizio.
Grazie ai nostri dati relativi alla composizione puoi, ad esempio, vedere quale carrozza di un determinato treno (con un determinato numero del treno) offre un accesso a pianale ribassato, ovvero un comodo accesso per sedie a rotelle o passeggini.
Con la «Train Formation Visualization» mettiamo inoltre a disposizione una visualizzazione che mostra i dati dell’API per un treno, vedi lo screenshot seguente. A tale scopo, è necessario verificare dapprima il numero del treno dall’orario online, ad es. da https://www.bls.ch.
https://opentdatach.github.io/train-formation-view
Accesso al API
Nota bene:
Nota: Una descrizione di come accedere alle API è disponibile qui: Howto: Accesso alle nostre API con API Keys.
Descrizione del funzionamento
Chi sta dietro tutto questo?
Il servizio è fornito in Svizzera dal team Attività di sistema Informazioni alla clientela Plus (SKI+) su incarico dell’Ufficio federale dei trasporti (UFT).
Acquisiamo i dati relativi alle formazioni da questi due sistemi:
- Al servizio di formazione (FOS) delle FFS, presso la quale operano diverse imprese di trasporto ferroviario (EVU) i propri dati relativi alla formazione. L’elenco delle EVU limitata a coloro che hanno acconsentito all’utilizzo dei loro dati relativi alla formazione.
- Interfaccia dei mezzi di trasporto del sistema in tempo reale (CUS) di Attività di sistema Informazione alla clientela (SKI). Il CUS gestisce i dati in tempo reale di tutti i mezzi di trasporto dei trasporti pubblici della Svizzera.
Mentre l’interfaccia FOS fornisce solo dettagli sulle formazioni, l’interfaccia CUS arricchisce i dati con ulteriori dettagli, soprattutto con la posizione dei veicoli (settori) sul binario delle fermate.
Perché opentransportdata.swiss lo offre?
I dati sulla composizione di un treno possono essere utilizzati per informare gli utenti:
- in quale settore di una stazione è possibile l’accesso accessibile con sedia a rotelle, aspetto particolarmente importante nell’ambito della legge sui disabili (LDis);
- in quale carrozza sono disponibili ganci per biciclette,
- quanti posti sono disponibili in generale in una carrozza,
- in combinazione con il nostro Previsione dell’occupazione è persino possibile visualizzare le previsioni di occupazione del treno,
- quali tipi di locomotive e carrozze circolano su quali tratte, per trainspotter o per imprese di trasporto che combinano i loro servizi con altre ferrovie.
Descrizione tecnica
Quali servizi (endpoint di interfaccia) offre il nostro Train Formation Service?
Il nostro Train Formation Service supporta le tre varianti seguenti. I dettagli delle richieste sono documentati anche tramite l’interfaccia OpenAPI:
- Basato su fermata – https://api.opentransportdata.swiss/formation/v2/formations_stop_based:
- Questo servizio fornisce le formazioni per ogni singola fermata della corsa di un treno.
- Parametri:
- Il nome di un EVU.
- Un giorno d’esercizio: Giorno per il quale occorre consultare la formazione. La data non può essere già passata. Attenzione: la data può essere solo quella di oggi (per l’inclusione dei dati in tempo reale dal CUS).
- Il numero del treno, detto anche «numero del mezzo di trasporto»: Il treno per il quale si desidera richiedere la composizione. Questo numero può essere ottenuto in diversi modi, tra cui i nostri dati dell’orario in diversi formati.
- Valori restituiti: una struttura dati JSON con:
- le fermate di un treno, con i relativi dettagli, la formazione con cui il treno parte dalle fermate e quando, da quale binario e quali locomotive/carri devono restare insieme fino a dove. È fondamentale indicare la formazione in una formula compatta, che abbia origine nel CUS.
- Questa richiesta non include tutti i dettagli di ogni carrozza.
- L’interpretazione della stringa di formazione viene descritta più avanti.
- Possibile caso applicativo: Mostrare la formazione di un treno su un binario per una determinata fermata.
- Basato su treni – https://api.opentransportdata.swiss/formation/v2/formations_vehicle_based:
- Questo servizio fornisce le formazioni per ogni veicolo (cioè per ogni elemento della formazione) del treno.
- Parametri:
- Gli stessi di quelli
formations_stop_based. - Giorno d’esercizio: Giorno per il quale occorre consultare la formazione. La data può situarsi fino a tre giorni nel futuro.
- Gli stessi di quelli
- Valori restituiti: una struttura dati JSON con:
- gli elementi della formazione con i dettagli di ogni veicolo, la posizione del veicolo nella formazione, le fermate in cui il veicolo si ferma lungo la corsa, con i dettagli relativi alla fermata e il binario e il settore in cui il veicolo si ferma nelle rispettive fermate.
- Questa richiesta non include una panoramica del treno lungo le fermate.
- Possibile caso applicativo: Tracciamento di un carro specifico.
- Basata su fermata e treno – https://api.opentransportdata.swiss/formation/v2/formations_full
- Questo servizio fornisce le formazioni sia per ogni fermata, sia per ogni veicolo.
- Parametro: analogo a quelli delle formazioni_stop_based e formazioni_vehicle_based.
- Valori restituiti: una struttura dati JSON con le fermate e gli elementi della formazione come per le rispettive varianti descritte sopra.
- Informazioni di stato sul servizio – https://api.opentransportdata.swiss/formation/v2/health
- Questo endpoint fornisce lo stato dell’esercizio attuale.
- Parametri: nessuno.
- Valori restituiti: una struttura dati JSON con lo stato operativo attuale del servizio.
I parametri della query
I seguenti parametri vengono passati come parametri di query (query parameters) dopo un ‘?’ nell’URL (GET request):
| Parametri | Descrizione del valore e valore esemplificativo |
|---|---|
evu |
Il EVU (Impresa di trasporto ferroviario) per la quale deve essere presentata la richiesta. Attualmente sono supportati: BLSP, FFS Viaggiatori, MBC, ÖBB, RhB, SOB, THURBO, TPF, TRN, VDBB, ZB. |
operationDate |
La data di partenza del treno e per la quale si intende presentare la richiesta. Esempio: 2024-09-18. |
trainNumber |
Il numero del treno per il quale si vogliono consultare i dati della formazione. Esempio: 2806. |
Una richiesta esemplificativa potrebbe quindi essere: https://api.opentransportdata.swiss/formation/v2/formations_stop_based?evu=BLSP&operationDate=2025-08-28&trainNumber=2806
La risposta
In questa sede non descriveremo il modello di dati completo, ma rimanderemo al seguente YAML:
Interpretazione della stringa corta di formazione:
In linea di massima la struttura di una stringa si differenzia a seconda che un binario abbia settori o che questi siano noti.
In ogni caso, per la struttura vale quanto segue:
| Elemento | Descrizione |
|---|---|
| Settore | Lettera („A“ … „Z“) |
| «Status» (Stato) | „-“ Veicolo chiuso
„>“ Veicolo con gruppi che accedono in questo punto d’esercizio
„=“ Veicolo (parzialmente) riservato per gruppi in transito
„%“ Veicolo aperto ma non servito (solo nelle carrozze ristorante)
Nota: «chiuso» può comparire solo da solo, gli altri caratteri possono essere combinati |
| [ | Inizio del gruppo di veicoli di appartenenza del treno
Nota: In questo modo si possono distinguere i veicoli ricoverati o da rimuovere dai veicoli appartenenti al treno in movimento. |
| ]
|
Fine del gruppo di veicoli di appartenenza al treno
Nota: In questo modo si possono distinguere i veicoli ricoverati o da rimuovere dai veicoli appartenenti al treno in movimento. |
| (
|
non è possibile passare al veicolo attiguo su questo lato del veicolo
Nota: Il calcolo si basa su dati anagrafici e ipotesi. Non è possibile garantire che tali dati corrispondano in ogni caso alla realtà. |
| )
|
non è possibile passare al veicolo attiguo su questo lato del veicolo
Nota: Il calcolo si basa su dati anagrafici e ipotesi. Non è possibile garantire che tali dati corrispondano in ogni caso alla realtà. |
| Tipo di vclKI
|
Tipo di veicolo dal punto di vista dell’informazione alla clientela. Legenda:
– «1» carrozza di 1a classe – «2» carrozze passeggeri di seconda classe (anche A/AB declassate) – «12» carrozze viaggiatori di 1a e 2a classe – Carrozza cuccette «CC» – Carrozza famiglia «FA» – Carrozza letti «WL» – Ristorante «WR» (carrozza bistrot, carrozza ristorante, ecc.) – «W1» carrozza ristorante e carrozza con posti a sedere di 1a classe – «W2» carrozza ristorante combinata e carrozza con posti a sedere di seconda classe – veicolo motore «LK» – Carrello portabagagli «D» – «F» vettura fittizia – «K» Veicolo senza classe – «X» carro ricoverato Nota: CUS trasforma il tipo di veicolo riferito da FOS in un «tipo KI» generico. Vengono impiegate le seguenti varianti: 1. Conversione di veicoli troppo lunghi: Gli elettrotreni che forniscono la fonte non una carrozza per carrozza, ma come un veicolo (troppo lungo), possono essere scomposti in singoli veicoli nella configurazione del CUS. Nella stringa quindi non appare 1 veicolo (generalmente del tipo „12“), bensì 2…n veicoli del tipo „1“, „2“, „12“ oppure „D“. Il numero è determinato in base al numero di veicoli percepito dal cliente. I veicoli di questo tipo che non conducono la prima classe al centro del treno sono di regola immatricolati in veicoli senza classi del tipo „K“ convertiti.
2. Conversione di singoli veicoli in base a termini regolari: Tutti i singoli veicoli vengono trasformati in veicoli KI generici utilizzando termini regolari priorizzati. 3. Conversione di veicoli singoli in base al numero di posti a sedere: Se non coincide l’espressione regolare di 2), viene determinato il tipo sulla base del numero di posti a sedere di 1a e 2a classe. Se il veicolo non dispone di posti a sedere, viene indicato il tipo „D“ del collaboratore.
Nota su “F”: sui binari con settori, il delta tra la lunghezza del treno e la lunghezza del bordo fermata viene riempito anteriormente e/o posteriormente con carri fittizi.
Nota su “X”: i carri ricoverati influenzano l’attribuzione dei veicoli di un treno ai settori, ma non fanno parte del treno interessato. |
| N° Ord | Numero d’ordine della prenotazione del posto singolo visualizzato così sulla carrozza per i viaggiatori (numero da 1 a 3 cifre) |
| Offerta | Elenco delle offerte relative ai veicoli. Queste includono:
– „BHP“ Posti per sedie a rotelle
– „BZ“ Zona business
– „FZ“ Zona famiglia
– „KW“ Piattaforma per passeggini
– „NF“ Veicolo con accesso a piano ribassato
– „VH“ Ganci/piattaforma per biciclette
– „VR“ ganci/piattaforma per biciclette con obbligo di prenotazione |
Quali sono i termini e i concetti più importanti che dovresti conoscere?
Come parte della nostra interfaccia utilizziamo i seguenti elementi (senza elementi del contenitore):
StopPoint- Uno StopPoint è una fermata lungo l’orario.
StopTime- Gli orari di partenza e d’arrivo.
Track- Il binario allo stoppoint.
FormationShortString- Breve rappresentazione della formazione (come definito da CUS).
VehicleGoal- Quali carri restano uniti e fino a quale destinazione (visto da una fermata).
JourneyMetaInformation- Identificazione univoca della corsa.
TrainMetaInformation- Proprietà descrittive del treno.
FormationMetaInformation- Dettagli sull’intera formazione, ad esempio il numero di veicoli.
ScheduledStop- StopPoint, StopTime, Track, Dettagli sulla gestione del treno alla fermata (ad es. se il treno si ferma o transita), nonché scostamenti della corsa (ad es. ritardi all’arrivo).
VehicleIdentifier- Attributi che identificano in modo univoco un veicolo, come ad esempio european vehicle number (EVN). Una particolarità consiste nel fatto che un veicolo può far parte di un treno articolato e quindi non può EVN ma solo una «generata». In questo caso si passa alla «Parent-EVN«.
WheelchairSymbolProperties- Proprietà necessarie per la determinazione del simbolo della sedia a rotelle (vedi anche Accessibilità nelle informazioni sull’orario).
AccessibilityProperties- Altre caratteristiche che possono essere utilizzate nell’ottica della rappresentazione conforme alle esigenze dei disabili.
PictoProperties- Se su un veicolo vengono rappresentati i diversi pittogrammi.
DirectTrolleyInformation- Quando la formazione è composta da carrozze dirette.
VehicleRelation- Questo elemento consente di seguire la corsa precedente e successiva della formazione data, che può anche essere una corsa diretta.
VehicleProperties- Le caratteristiche di un veicolo come componente di una formazione, ossia un elemento della formazione, nonché di dove e a dove il veicolo è parte della formazione.
FormationVehicleAtScheduledStop- Visualizzazione della formazione per fermata (per la richiesta vehicle_based).
VehicleRelationship- La relazione di corsa, cioè come la corsa cambia tra due corse (ad esempio in caso di soppressione).
VehicleRelationshipDetails- I dettagli di una relazione di corsa.
Limitazioni
- I dati sono limitati alle imprese di trasporto ferroviario (EVU)Che allestiscono le loro formazioni tramite le Ferrovie federali svizzere (FFS) e hanno accettato la pubblicazione dei loro dati come Open Data.
- Il servizio mette a disposizione tutti i dati e i dati basati sul veicolo solo se tutte le fonti hanno tutti i dati necessari. Ciò è particolarmente importante se si considera che il CUS ha solo dati della situazione odierna.
- Concretamente, i dati provengono dal sistema in tempo reale SKI (CUS – CUstomer Information System – VerkehrsMittel VM) e il Formation Services (FOS) delle FFS.