Skip to content
LoginRegister
DEENFRIT
Home
Piattaforma open data sulla mobilità in Svizzera
  2. Cookbook
  3. Open Journey Planner (OJP)

Open Journey Planner (OJP)

Informazioni aggiornate a gennaio 2024 Potete trovare informazioni sulle continue modifiche nel nostro Changelog.

Fondo

Che cos’è l’OJP?

L’abbreviazione ha tre significati:

  1. Lo standard di interfaccia CEN/TS 17118 “Open API for Distributed Journey Planning“, dichiarato vincolante per gli Stati membri dell’Unione Europea nel Regolamento delegato (UE 2017/1926).
  2. Il sistema di backend di routing “Open Journey Planner” per il calcolo dei percorsi con i mezzi pubblici, i sentieri e altre opzioni di mobilità.
  3. L’interfaccia OJP, cioè l’interfaccia del sistema OJP corrispondente allo standard OJP. Nel suo nucleo, è uno standard XML con un comportamento di richiesta/risposta. Come per tutte le norme CEN, è in fase di sviluppo un profilo per la Svizzera (cosa è supportato e cosa no). Il profilo è collegato qui (solo in  tedesco).

Su questa piattaforma di dati aperti, l’abbreviazione “OJP” è solitamente utilizzata per il sistema “Open Journey Planner”, salvo diversa indicazione.

In questa pagina si distingue tra standard OJP (standard CEN), sistema OJP (sistema di routing) e interfaccia OJP.

Chi sta dietro tutto ciò?

Come descritto in precedenza, lo standard OJP è promosso dal Comité Européen de Normalisation (CEN). L’ufficio System Tasks Customer Information Plus (SKI+) è attivamente coinvolto nell’ulteriore sviluppo dello standard OJP per conto dell’Ufficio federale dei trasporti (UFT). Lo standard OJP si basa sullo standard Network Timetable Exchange (NeTEx) del CEN. I modelli di dati di entrambi gli standard implementano a loro volta il modello di dati di riferimento per il trasporto pubblico in Europa, noto come Transmodel.

Il sistema OJP è sviluppato da un fornitore di servizi esterno a SKI+. Il sistema si basa su un prodotto proprietario del fornitore esterno di servizi. Il sistema OJP può essere controllato utilizzando lo standard OJP.

L’interfaccia OJP si basa sul Travellers Realtime Information Advisory Standard (TRIAS), che segue la direttiva 431 dell’Associazione delle aziende di trasporto tedesche (VDV).

Una demo per provare il sistema OJP utilizzando lo standard OJP è disponibile qui: OJP Demo

Ulteriori informazioni sulla valutazione di OJP come standard sono contenute nel rapporto dell’UFT (solo tedesco).

Perché la piattaforma Open Data offre questo?

Lo standard OJP consente un’interfaccia aperta e standardizzata per la “pianificazione distribuita dei percorsi”. Sistemi diversi possono quindi lavorare insieme secondo questo standard sviluppato a livello europeo per offrire una pianificazione di viaggio transfrontaliera o integrata o per abilitare nuovi servizi informativi innovativi.

Il sistema OJP serve a soddisfare il mandato dell’UFT per un router non discriminatorio e intermodale che possa essere controllato tramite un’interfaccia conforme allo standard OJP. Il sistema OJP è destinato ad essere utilizzato per lo sviluppo di applicazioni per i clienti finali. Il contatto diretto con i clienti e i loro dati rimane con queste applicazioni per i clienti finali!

È importante capire che, nonostante i nomi simili, il router e lo standard sono due cose essenzialmente indipendenti.

Come si accede ai dati/interfacce?

Dati

Come descritto, OJP è uno standard/sistema/interfaccia, quindi non c’è alcun download di file.

Tuttavia, vi consigliamo di consultare il link alla pagina GitHub o la nostra interfaccia API per vedere un paio di esempi pratici.

Interface

Interfacce

Dettagli sull’API OJP: https://opentransportdata.swiss/it/dataset/ojp2020 (produttivo dal 2020)

Dettagli sull’API OJP (2.0): https://opentransportdata.swiss/de/dataset/ojp2-0 (produttivo, ancora in costruzione)

Dettagli sull’API OJP-Fare: https://opentransportdata.swiss/it/dataset/ojpfare (ricerca)

Descrizione

Attenzione: la seguente descrizione si riferisce a OJP2020 (cioè OJP-API v1.0). Per lavorare con OJP-API 2.0 vedere https://opentransportdata.swiss/de/cookbook/ojp2entwicklung/.

Quali servizi (endpoint di interfaccia) offre lo standard OJP?

Lo standard OJP definisce diversi endpoint di interfaccia (di seguito denominati “servizi”). Nella versione 1.0 ci sono 7 “core services” e nella versione 2.0 ci sono 9 “core services”. Questi servizi sono serviti dal sistema OJP.

Il sistema OJP supporta tutti e 7 i servizi della versione 1.0 che possono essere richiamati e collegati (LinkedServices, descritti nella sezione tecnica seguente). Ordinati per importanza:

  1. La vostra situazione: volete calcolare un percorso con la vostra famiglia utilizzando diversi mezzi di trasporto?
    • Quindi è necessario il TripRequest
    • Cosa fa il servizio: Con questo servizio, il sistema operativo (nel nostro caso il sistema OJP) effettua il routing.
    • Cosa serve: Quando si inserisce un punto di partenza e una destinazione (coordinata, indirizzo, PDI o fermata), il sistema OJP calcola i collegamenti dal punto di partenza alla destinazione. È possibile richiedere diverse modalità con ModesToCover. Attualmente sono disponibili le seguenti modalità: trasporto pubblico; percorso pedonale; bicicletta; auto a guida autonoma; servizi di condivisione (bicicletta, e-scooter, car sharing).
    • Cosa offre il servizio di back: L’itinerario comprende sia l’itinerario dei trasporti pubblici (che tiene conto dei tempi di percorrenza attuali e delle interruzioni) sia l’itinerario dei trasporti individuali su mappa (ad esempio con la propria auto) basato su OpenStreetMap (OSM). Se lo si desidera, è possibile utilizzare il parametro di uscita Link-Projection per richiedere i percorsi geografici effettivi; per i percorsi pedonali è solitamente disponibile anche una TurnDescription (navigazione descritta verbalmente).
    • Maggiori dettagli su questo servizio sono disponibili al seguente link: OJPTripRequest
  2. La vostra situazione: volete mostrare ai vostri ospiti le fermate e i punti di interesse del vostro quartiere?
    • Quindi è necessaria LocationInformationRequest (la richiesta di informazioni sulla posizione)
    • Cosa fa il servizio: Questo servizio determina le località più vicine.
    • Di cosa ha bisogno il servizio: quando si inserisce una coordinata o un indirizzo, il sistema OJP utilizza una ricerca a raggio per determinare i luoghi corrispondenti.
    • Cosa fornisce il servizio: le fermate e i punti di interesse vicini alla posizione specificata.
    • Ulteriori dettagli su questo servizio sono disponibili al seguente link: OJPLocationInformationRequest
  3. La vostra situazione: volete un monitor di partenza per la fermata dell’autobus di fronte al vostro negozio?
    • Quindi è necessaria StopEventRequest
    • Cosa fa il servizio: Il servizio determina gli orari di partenza e di arrivo di una fermata.
    • Cosa serve al servizio: è necessario inserire una fermata specifica.
    • Cosa fornisce il servizio: le prossime partenze/arrivi a una specifica fermata.
    • Ulteriori dettagli su questo servizio sono disponibili al seguente link: OJPStopEventRequest
  4. La vostra situazione: avete bisogno di tutte le fermate lungo il percorso precedentemente calcolato?
    • Quindi è necessaria la richiesta TripInfoRequest
    • Cosa fa il servizio: Questo servizio determina ulteriori dettagli su un viaggio che è già stato calcolato (vedi TripRequest).
    • Di cosa ha bisogno il servizio: deve essere fornito il viaggio precedentemente stabilito.
    • Cosa fornisce il servizio: dettagli di un viaggio già calcolato.
    • Ulteriori dettagli su questo servizio sono disponibili al seguente link: OJPTripInfoRequest
  5. La vostra situazione: volete sapere quanto potrebbe costare il viaggio che avete richiesto?
    • Quindi è necessaria la richiesta di tariffa (FareRequest)
    • Cosa fa il servizio: determina il costo stimato di un viaggio trasferito utilizzando l’infrastruttura di calcolo dei costi dei trasporti pubblici della Svizzera.
    • Di cosa ha bisogno il servizio: deve essere fornito il “viaggio” precedentemente stabilito.
    • Cosa offre il servizio: il calcolo del prezzo dei viaggi, compresi i viaggi scontati e la considerazione dell’Half Fare Travelcard (“HTA”). Le richieste di prezzo sono possibili solo in Svizzera. IMPORTANTE: le informazioni sui prezzi non sono vincolanti. Il prezzo effettivo non viene definito fino all’invio dell’ordine. Anche il numero di richieste è limitato.
    • Maggiori dettagli su questo servizio sono disponibili al seguente link: Alpha: OJP Fares
  6. La vostra situazione: Volete pianificare un viaggio in Austria e trovare punti di trasferimento adatti?
    • Quindi è necessaria la richiesta ExchangePointRequest
    • Cosa fa il servizio: fornisce un elenco di fermate che possono essere utilizzate come punti di passaggio tra due regioni. L’interrogazione fa parte del calcolo del percorso distribuito dello standard OJP. Le regioni sono quelle servite da altri sistemi distribuiti.
    • Cosa serve al servizio: una posizione specifica per la quale devono essere ricercate le fermate di transizione verso i sistemi vicini, nonché i parametri corrispondenti, ad esempio sul tipo di posizione (POI, fermata, ecc.).
    • Cosa fornisce il servizio: o le fermate di transizione per la località richiesta, o tutte le fermate di transizione che possono essere utilizzate per il calcolo del percorso.
    • Non ci sono ancora ulteriori dettagli su questo servizio.
  7. La vostra situazione: volete calcolare un itinerario da Berna a vostra zia a Zurigo e fare prima una sosta a Olten?
    • Quindi è necessaria la richiesta MultiPointTripRequest
    • Cosa fa il servizio: Con questo servizio, il sistema operativo (nel nostro caso il sistema OJP) esegue un instradamento, proprio come la TripRequest.
    • Cosa serve al servizio: Oltre al punto di partenza e a un punto di destinazione (coordinata, indirizzo, PDI o fermata) (come nel caso di TripRequest), sono necessari punti intermedi che devono essere esplicitamente inclusi o esclusi.
    • Cosa offre il servizio: Lo stesso di TripRequest e L’itinerario comprende sia un itinerario del trasporto pubblico (che tiene conto dei tempi di percorrenza attuali e delle interruzioni) sia un itinerario del trasporto individuale su mappa (ad esempio con la propria auto) basato su OpenStreetMap (OSM). Se lo si desidera, è possibile utilizzare il parametro di uscita Link-Projection per richiedere i percorsi geografici effettivi; per i percorsi pedonali è solitamente disponibile anche una TurnDescription (navigazione descritta verbalmente).
    • Non ci sono ancora ulteriori dettagli su questo servizio.
  8. La vostra situazione: avete fatto calcolare un percorso qualche giorno fa. È arrivato il giorno del viaggio e volete consultare le informazioni più recenti?
    • Quindi è necessaria la (dalla versione 2.0) TripRefinementRequest
    • Cosa fa il servizio: aggiorna un viaggio già calcolato. È importante notare che la richiesta non è un ricalcolo!
    • Cosa serve al servizio: un viaggio esistente con contesto e parametri. I parametri possono fungere da filtro, ad esempio per consegnare solo i risultati parziali che non contengono passi.
    • Cosa offre il servizio: Il servizio aggiorna il viaggio con le aggiunte desiderate, se disponibili. Importante:
      • È possibile che il servizio fornisca diversi viaggi e non (solo) quello richiesto.
      • Può accadere che il viaggio precedente venga “interrotto” durante questa ricerca. Il viaggio deve quindi essere ricalcolato.
      • La risposta di TripRefinementRequest deve quindi essere sempre controllata!
    • Non ci sono ancora ulteriori dettagli su questo servizio.
  9. La tua situazione: Hai bisogno di prolungare la tua sosta prevista a Olten? 
    • Quindi è necessaria la (dalla versione 2.0) TripChangeRequest
    • Cosa fa il servizio: consente di prolungare il tempo di permanenza in una tappa del viaggio e di ottenere la sezione prima o dopo. Le altre parti potrebbero quindi essere ricalcolate.
    • Cosa serve al servizio: una gamba esistente e le modifiche desiderate.
    • Cosa offre il servizio: Un viaggio personalizzato in base ai vostri desideri.
    • Non ci sono ancora ulteriori dettagli su questo servizio.
  10. SysRequest:
    1. Oltre ai 7 o 9 servizi di base, è anche possibile interrogare lo stato dell’OJP (versione/formato della data/ecc.).
    2. Ulteriori dettagli su questo servizio sono disponibili al seguente link: OJP Sysrequest

Quali sono i termini e i concetti più importanti da conoscere?

Per essere in grado di utilizzare l’interfaccia OJP, è necessario interiorizzare i seguenti termini e concetti.

  • StopPoint
    • Descrizione: un punto di fermata è una fermata lungo un orario. Può trattarsi di una fermata, di un binario, di un settore, di un bordo di fermata o anche di un elemento dinamico. Lo StopPoint è assegnato allo StopPlace tramite uno StopAssignment.
  • StopPlace
    • Descrizione: lo StopPlace è la rappresentazione fisica di una fermata. Uno StopPlace può avere dimensioni diverse. Le fermate molto grandi, come le stazioni ferroviarie di Berna o Zurigo, sono composte da più StopPlaces.
  • Journey, il “viaggio”
    • Descrizione: Un viaggio è il trasporto di clienti su un percorso specifico, un collegamento orario specifico, con un mezzo di trasporto specifico, a un’ora specifica, in una direzione specifica. Esistono diversi tipi di viaggio, ad esempio: DatedJourney per un viaggio di un mezzo di trasporto in un giorno specifico.
  • Trip, il “viaggio”
    • Descrizione: Un “viaggio” e quindi una forma non specifica di un viaggio più concreto. Un viaggio è composto da tappe (vedi sotto).
  • Leg (gamba), la “sezione viaggiante”
    • Descrizione: una sezione di un viaggio. Sono disponibili i seguenti tipi di gamba:
      • ContinuousLeg: una tratta non vincolata a un orario.
      • TimedLeg: Leg (gamba) secondo un orario.
      • TransferLeg: Leg (gamba) per una posizione in cui avviene un trasferimento.
  • Direction
    • Descrizione: Tutte le linee e i viaggi hanno una direzione. Questo aiuta soprattutto le aziende di trasporto nella pianificazione e, se necessario, nella visualizzazione di una “stazione di arrivo/destinazione”. Si tratta quindi di un “attributo artificiale” e non è possibile ricavare il significato della direzione.
  • Facility
    • Descrizione: Una struttura è un elemento disponibile in un “luogo” (ad esempio, una fermata dell’autobus) o su un “servizio” (ad esempio, un veicolo). Un esempio è la toilette della stazione ferroviaria o il vagone ristorante. Attualmente sono ricavati dalle offerte dell’HRDF (vedi informazioni sul trasporto). La mappatura viene effettuata in base a Notes2FacilitiesMappingFile.
  • Mode
    • Descrizione: I modi sono possibili mezzi di trasporto. Le modalità consentite sono:
      • ContinuousMode: modalità che non dipende da un programma.
      • IndividualModes: Trasporto individuale.
      • PtMode: PtMode è una modalità del trasporto pubblico.
      • TransferModes: modalità relativa al trasferimento
      • XXXRef: questi elementi sono riferimenti. Alla fine, si tratterà di documenti d’identità generici per tutta la Svizzera. Tuttavia, questi sono ancora in fase di costruzione. Ci sarà un’evoluzione.

Descrizione tecnica

Accesso all’API

Per poter utilizzare l’API/interfaccia è necessario un token. Questo token può essere ottenuto tramite il Developer Portal (portale sviluppatori).

Tutti i servizi della versione 1.0 sono disponibili tramite POST con l’URL https://api.opentransportdata.swiss/ojp2020.

Tutti i servizi della versione 2.0 sono disponibili via POST con l’URL https://api.opentransportdata.swiss/ojp20.

Potete provare l’interfaccia qui https://opentransportdata.swiss/it/cookbook/open-journey-planner-ojp-api-explorer/ o https://opentdatach.github.io/api-explorer2/ .

Funzionalità di base API

Richieste semplici

L’interfaccia OJP è più simile a una classica interfaccia XML SOAP che a un’interfaccia REST. Tutti gli accessi vengono effettuati tramite l’endpoint specificato.

È necessario impostare due intestazioni:

La chiave di lavoro attuale è:

I servizi sopra descritti sono differenziati tramite le richieste corrispondenti nell’elemento ServiceRequest. In questo esempio, stiamo eseguendo una LocationInformationRequest.

Assicurarsi di inserire una voce unica come RequestorRef. L’obiettivo è identificare chi sta facendo la richiesta. La specifica dovrebbe includere il suffisso “_test”, “_int” o “_prod”, in modo da sapere a quale ambiente si è acceduto in caso di successive analisi e richieste di supporto.

Più richieste in un unico messaggio

È possibile inserire un numero qualsiasi di OJPXXXRequest diverse all’interno di una ServiceRequest. Non devono essere necessariamente dello stesso tipo.

Attenzione: le risposte non sono ordinate secondo l’ordine delle richieste effettuate, ma secondo la sequenza dell’XSD standard. È quindi estremamente importante per queste richieste che gli identificatori dei messaggi siano impostati per ogni richiesta e possano essere letti dalla risposta. La sequenza standard è (versione 1.0):

  • ExchangePointsRequest (Richiesta di punti di scambio)
  • FareRequest (Richiesta di tariffa)
  • LocationInformationRequest (Richiesta di informazioni sulla posizione)
  • MultiPointRequest (Richiesta multipunto)
  • StopEventRequest (Richiesta di arresto dell’evento)
  • TripInfoRequest (Richiesta di informazioni sul viaggio)
  • TripRequest (Richiesta di viaggio)

Restrizioni e ulteriori informazioni

Restrizioni

  • Le varie modalità non sono ancora disponibili.
  • Le informazioni in tempo reale sono disponibili solo se abbiamo ricevuto queste informazioni e possiamo ottenerle tramite CUS.
  • Le informazioni sui guasti non sono ancora disponibili.

Ulteriori indicazioni