GTFS Realtime (GTFS-RT)

Descrizione breve

GTFS Realtime (GTFS-RT) è un ampliamento di GTFS Static che arricchisce le informazioni statiche di transito con informazioni in tempo reale. I dati in tempo reale GTFS sono coordinati con i dati statici GTFS. Il feed in tempo reale comprende tutte le modifiche note nei trasporti pubblici svizzeri nell’intera finestra di anteprima (tre ore) per tutte le imprese di trasporto che forniscono dati in tempo reale.

Descrizione del funzionamento

GTFS-RT consente di integrare le informazioni statiche sul transito con tre diversi tipi di informazioni supplementari. Queste tre aggiunte sono solitamente rese disponibili singolarmente tramite HTTP e aggiornate regolarmente, in modo che gli sviluppatori possano scegliere con quali dati in tempo reale integrare le loro applicazioni.

I tre tipi di informazioni supplementari sono:

• Trip Updates (principalmente descritti qui)
• Service Alerts (GTFS-SA)
• Vehicle Positions (non vengono pubblicate sulla piattaforma open data sulla mobilità in Svizzera)

Il profilo GTFS svizzero, che descrive nel dettaglio le caratteristiche adottate dallo standard o le deroghe allo standard, è disponibile qui: https://www.oev-info.ch/datenmanagement/ski/standards-der-ski (il link rimanda alla pagina di riepilogo, poiché il documento (General Transit Feed Specification (GTFS) PROFILE SWITZERLAND) è attualmente soggetto a frequenti modifiche).

Nota bene: Nei giorni festivi (ad es. lunedì di Pasqua, lunedì di Pentecoste ecc.) non vengono effettuati aggiornamenti.

Trip Updates

Esempio: «L’autobus 18 è in ritardo di 10 minuti».

Su questa pagina vengono costantemente pubblicati i ritardi, le modifiche agli itinerari, i veicoli sostitutivi o le soppressioni di singole linee, in modo tale da consentire ai viaggiatori una pianificazione il più accurata possibile.

Finché tramite VDV454 non sarà sempre fornito un SJYID, nei casi in cui non è presente alcun SJYID, l’identificatore corsa VDV454 in GTFS-RT sarà fornito in original_trip_id:

// Matches the original_trip_id in GTFS static.
optional string original_trip_id = 8;

Service Alerts

Esempio: «La fermata Berna, Weissenbühl è attualmente chiusa a causa di un incidente.»

In caso di spostamento del bordo fermata o di eventi imprevisti generali con ripercussioni su una fermata, su un itinerario o sull’intera rete, è possibile pubblicare brevi annunci per tenere informati i viaggiatori e spiegare il motivo della modifica.

Record GTFS RT: Service Alerts (informazioni sugli eventi)

Cookbook: GTFS-RT: Service Alerts (informazioni sugli eventi della Svizzera)

«Vehicle Positions» (Posizioni veicolo)

Esempio: «Questo autobus si trova alle 18:23 alla fermata Bern, Bahnhof.»

Qui è possibile pubblicare informazioni sull’ubicazione dei singoli veicoli in transito. Possono essere inoltre forniti anche l’attuale occupazione del veicolo, il tipo di veicolo o informazioni simili.

Le Vehicle Positions non sono disponibili sulla piattaforma.

Concetti importanti

• GTFS Static (noto anche come GTFS Schedule): Pubblicazione di informazioni statiche sul transito in formato GTFS.
• GTFS Realtime: Pubblicazione di informazioni di transito in tempo reale come arricchimento dei dati statici GTFS, sotto forma di buffer di protocollo.

I singoli elementi sono spiegati nel dettaglio nelle pagine dello standard indicate sopra e pertanto non tutti sono riportati in questa sede.

Descrizione tecnica

Gli aggiornamenti di viaggio sono forniti tramite una richiesta GET. Sono memorizzati nella cache per 30 secondi, quindi ci sono solo due volte al minuto nuovi dati.
Per ottimizzare il nostro caching, l’API Manager invia un redirect con un nuovo link, quindi quando si utilizza questo servizio, i redirect devono essere sempre attivati. Per molte librerie di codici, questo può essere fatto con parametri appropriati, come ad es. «allow_redirects».

Autorizzazione e Open Services

Per accedere a questa API è necessaria una API Key, Che può essere ottenuta dal nostro API Manager, vedere al riguardo le istruzioni all’indirizzo Howto: Accesso alle nostre API con API Key.

Numero massimo di richieste al minuto

È possibile utilizzare la chiave per eseguire al massimo due query al minuto sull’interfaccia. Si tratta di una finestra scorrevole.

Se le richieste vengono formulate troppo rapidamente, si riceve il seguente messaggio:

{
    "error": "Rate limit exceeded"
}

Riferimento a GFTS Static

Ogni feed GTFS-RT si basa su un GTFS Static. Questo viene messo a disposizione i lunedì e i giovedì (per i casi di perturbazione vedere sezione successiva). Ogni giorno alle 15.00 il feed GTFS-RT viene convertito al nuovo GTFS Static. Poiché gli identificatori («service_id», «trip_id») possono cambiare con qualsiasi versione di GTFS Static, è fondamentale fare riferimento al GTFS Static corretto per un’implementazione corretta dell’interfaccia.

Nell’intestazione, nell’elemento feed_version (scrittura in .json: FeedVersion) si rimanda alla versione GTFS Static corrispondente. Nella vista come JSON, l’intestazione potrebbe avere il seguente aspetto (utilizzare JSON solo a scopo di test, v. sotto):

  "Header": {
    "GtfsRealtimeVersion": "1.0",
    "Incrementality": "FullDataset",
    "Timestamp": 1727429583,
    "FeedVersion": "20240926"
  }

In caso di perturbazione

L’esportazione statica GTFS viene pubblicata il prima possibile, seguita da GTFS Realtime circa 5-6 ore dopo, ma non oltre le 18.00 dello stesso giorno. Se ciò non fosse possibile, i nuovi dati vengono attivati in GTFS Realtime il giorno successivo.

Esempio: È stato possibile pubblicare i nuovi dati statici GTFS solo nel pomeriggio. I dati in tempo reale GTFS verranno attivati il giorno successivo alle ore 8.00 circa.

URL per l’appello

HTTP GET auf https://api.opentransportdata.swiss/la/gtfs-rt

(Attenzione: Nessuna chiusura «/»)

Intestazione:

• Content-Type: «application/octet-stream»
• Lo user agent deve essere impostato (valore qualsiasi)
• «Accept-Encoding: br, gzip, deflate»
• Devono essere consentiti i reindirizzamenti.

Esempio in curl

curl -H "Authorization: Bearer eyJvcmciOiI2NDA2NTFhNTIyZmEwNTAwMDEyOWJiZTEiLCJpZCI6ImZjNzdjMzk2M2MwNjRjYzM4ZmNjOWZjYWQ4MjVlZWZkIiwiaCI6Im11cm11cjEyOCJ9"  -L -H "User-Agent: testuser" https://api.opentransportdata.swiss/la/gtfs-rt --compressed --output gtfs_rt_as_proto_buf.pb

Struttura dei dati (Protocol Buffer)

Il formato dati GTFS Realtime si basa sui Protocol Buffer, che è un meccanismo indipendente dalla lingua e dalla piattaforma per portare i dati in un ordine seriale. È progettato come formato binario, il che lo rende più piccolo, più veloce e più semplice rispetto a XML. La struttura dei dati è definita in un cosiddetto file gtfs-realtime.proto, utilizzato per generare codice sorgente per tradurre facilmente i dati strutturati in diverse lingue (Java, C++, Python ecc.).

Struttura dei dati (JSON)

In alternativa, la piattaforma fornisce anche un’implementazione JSON.

La richiesta avviene quindi tramite l’URL:

HTTP GET https://api.opentransportdata.swiss/la/gtfs-rt?format=JSON

Tuttavia, la variante JSON non è standardizzata.

Utilizzo di JSON solo a scopo di test

JSON può essere utilizzato a scopo di test solo se ad es. uno sviluppatore di una nuova app vuole visualizzare in forma leggibile quali dati sono contenuti nel nostro GTFS-RT.

Alla fine, l’interfaccia GTFS-RT non dovrebbe essere gestita in un JSON leggibile, ma in modo binario (senza ?FORMAT=JSON) per i seguenti motivi:

• binario è molto più performante di JSON e in JSON devono essere trasmessi e letti molti più dati (un messaggio JSON diventa grande fino a circa 11 MB),
• JSON non è specificato, mentre con GTFS-RT binario il client GTFS può fare affidamento sulla conformità allo standard GTFS-RT

Precisione

I ritardi hanno una precisione di decimi di minuto (0,1 min = 6 s).

Interpretazione dei dati

Per l’interpretazione esatta dei dati, consultare direttamente la specifica GTFS.

Il caso speciale principale sono i marciapiedi descritti sulla pagina GTFS.

Altri punti importanti

• GTFS-RT fornisce dati nuovi solo se qualcosa è cambiato. In questo caso il nostro sistema considera solo la previsione di partenza. Se la previsione di partenza resta invariata e cambia solo la previsione dell’arrivo, per la corsa in questione non viene generato alcun annuncio GTFS-RT.
• Se una corsa circola in orario, all’interno di StopTimeUpdate essa viene emessa con «Delay»: 0.
• Esempio

    {
      "id": ".ojp-92-206.1.TA.50.j26|20260624",
      "tripUpdate": {
        "trip": {
          "tripId": ".ojp-92-206.1.TA.50.j26",
          "startTime": "12:41:00",
          "startDate": "20260624",
          "scheduleRelationship": "SCHEDULED",
          "routeId": "92-206-j26-1",
          "originalTripId": "85:876:6037_103"
        },
        "stopTimeUpdate": [
          {
            "stopSequence": 1,
            "departure": {
              "delay": 0
            },
            "stopId": "ch:1:sloid:93924:0:2",
            "scheduleRelationship": "SCHEDULED"
          },
          {
            "stopSequence": 8,
            "arrival": {
              "delay": 30
            },
            "departure": {
              "delay": 30
            },
            "stopId": "ch:1:sloid:93932:0:1",
            "scheduleRelationship": "SCHEDULED"
          },
          {
            "stopSequence": 9,
            "arrival": {
              "delay": 0
            },
            "departure": {
              "delay": 0
            },
            "stopId": "ch:1:sloid:93933:0:1",
            "scheduleRelationship": "SCHEDULED"
          }
        ]
      }
    },

Domande & Risposte