Dati stradali in tempo reale

I dati stradali in tempo reale forniscono aggiornamenti sulle condizioni stradali e sugli eventi per i percorsi selezionati, supportando il monitoraggio dinamico e la risposta rapida. Questi dati sono diversi da quelli raccolti periodicamente disponibili in BigQuery e sono adatti a scenari che richiedono informazioni tempestive.

Questi dati vengono trasmessi in streaming in modo continuo e includono la durata del viaggio, che indica i tempi di percorrenza su un percorso, e gli intervalli di lettura della velocità, che mostrano la densità del traffico lungo il percorso.

Per accedere ai dati stradali in tempo reale, il tuo contratto deve includere il pacchetto Real-Time Operations.

Crea una sottoscrizione Pub/Sub per gli intervalli di lettura della velocità e della durata del viaggio

Ti verranno forniti argomenti Google Cloud Pub/Sub dedicati, a cui potrai iscriverti per ricevere i dati in tempo reale per tutti i tuoi itinerari creati.

Il seguente esempio di codice mostra il formato dell'argomento utilizzando la codifica binaria:

projects/maps-platform-roads-management/topics/rmi-roadsinformation-PROJECT_NUMBER

Forniamo anche un altro argomento utilizzando la codifica JSON (con il suffisso -json). Devi iscriverti all'argomento Pub/Sub fornito per ricevere messaggi di dati in tempo reale. Consulta la sezione Iscriviti a un argomento per una rapida panoramica su come iscriversi e utilizzare i messaggi di un argomento Cloud Pub/Sub.

Schema Durata del viaggio e intervalli di lettura veloce

Ogni messaggio di dati in tempo reale incorpora dati come:

  • Dettagli della strada, come duration_in_seconds, static_duration_in_seconds, speed_reading_offsets (intervalli di lettura della velocità basati sull'offset) e retrieval_timestamp.
  • Identificatori di itinerario come selected_route_id e display_name.

Ogni messaggio viene pubblicato rispettando il seguente formato Protobuf.

syntax = "proto3";

// Contains the road information like travel duration and speed reading
// intervals for a selected route.
message RoadsInformation {
  // Legacy message. May stop being populated on or after November 9, 2026.
  // Use top-level duration_in_seconds and static_duration_in_seconds instead.
  message TravelDuration {
    // The duration of travel through the route based on current road
    // conditions.
    float duration_in_seconds = 1;
    // The duration of travel through the route without taking road
    // conditions into consideration.
    float static_duration_in_seconds = 2;
  }
  message Timestamp {
    // Represents seconds of UTC time since Unix epoch
    // 1970-01-01T00:00:00Z. Must be from 0001-01-01T00:00:00Z to
    // 9999-12-31T23:59:59Z inclusive.
    int64 seconds = 1;

    // Non-negative fractions of a second at nanosecond resolution. Negative
    // second values with fractions must still have non-negative nanos values
    // that count forward in time. Must be from 0 to 999,999,999
    // inclusive.
    int32 nanos = 2;
  }
  // Legacy message representing the latitude and longitude of a coordinate
  // within a coordinate-based speed reading interval.
  message LatLng {
    float latitude = 1;
    float longitude = 2;
  }
  // Legacy coordinate-based speed reading interval message. May stop being
  // populated on or after November 9, 2026. Use SpeedReadingOffset instead.
  message SpeedReadingInterval {
    // The coordinates on the polyline for the speed reading interval.
    repeated LatLng interval_coordinates = 1;

    // Describes the categorized current speed of road conditions.
    // Possible values are:
    // - "NORMAL": Road is flowing smoothly, no slowdown is detected.
    // - "SLOW": Slowdown detected, but no congestion formed.
    // - "TRAFFIC_JAM": Traffic jam detected. In this legacy field, heavy
    //   traffic jams (dark red) are also reported as "TRAFFIC_JAM";
    //   "TRAFFIC_JAM_HEAVY" is never used.
    string speed = 2;
  }
  // Offset-based speed reading interval along the route.
  message SpeedReadingOffset {
    // The distance offset from the start of the route in meters for the start
    // of the interval (inclusive).
    int32 start_offset = 1;

    // The distance offset from the start of the route in meters for the end of
    // the interval (exclusive; equals the start_offset of the subsequent
    // interval).
    int32 end_offset = 2;

    // Describes the categorized current speed of traffic, aligned with the
    // colors in the Google Maps traffic layer. Possible values are:
    // - "NORMAL" (green): Traffic is flowing smoothly, no slowdown is detected.
    // - "SLOW" (yellow): Slowdown detected, but no traffic jam formed.
    // - "TRAFFIC_JAM" (red): Traffic jam detected.
    // - "TRAFFIC_JAM_HEAVY" (dark red): Heavy traffic jam detected (available
    //   as of October 8, 2026).
    string speed = 3;
  }
  // Id for selected_route.
  string selected_route_id = 1;
  // User provided name for the route.
  string display_name = 2;
  // Legacy coordinate-based speed reading intervals. May stop being populated
  // on or after November 9, 2026. Use speed_reading_offsets instead.
  repeated SpeedReadingInterval speed_reading_intervals = 3;
  // Legacy travel time information. May stop being populated on or after
  // November 9, 2026. Use duration_in_seconds and static_duration_in_seconds
  // instead.
  TravelDuration travel_duration = 4;
  // Legacy timestamp when the road data was collected. May stop being populated
  // on or after November 9, 2026. Use retrieval_timestamp instead.
  Timestamp retrieval_time = 5;
  // Contains a geojson polyline representing the optimal route determined
  // based on user's input waypoints.
  string route_geometry = 6;
  // Road segment place IDs along the route. They follow topological order
  // and are always connected.
  repeated string road_segment_ids = 7;
  // Offset-based speed reading intervals representing traffic density across
  // the route; each interval is demarcated by the distance offset from the
  // start of the route.
  repeated SpeedReadingOffset speed_reading_offsets = 8;
  // The duration of travel through the route based on current traffic
  // conditions.
  float duration_in_seconds = 9;
  // The duration of travel through the route without taking traffic
  // conditions into consideration.
  float static_duration_in_seconds = 10;
  // The time the traffic data was collected, as an RFC 3339 UTC timestamp
  // string (for example, "2026-10-08T15:04:05+00:00").
  string retrieval_timestamp = 11;
}

Intervalli di lettura rapida basati sull'offset e migrazione dei campi

A partire dall'8 ottobre 2026, gli intervalli di velocità di lettura vengono forniti nel campo speed_reading_offsets basato sull'offset, in cui ogni intervallo è delimitato da start_offset (incluso) e end_offset (escluso) in metri dall'inizio del percorso e include la quarta categoria di velocità TRAFFIC_JAM_HEAVY. Per informazioni dettagliate sulle categorie di velocità e sui formati degli intervalli, vedi Intervalli di lettura veloce.

La tabella seguente mappa ogni campo Pub/Sub legacy (che potrebbe non essere più compilato a partire dal 9 novembre 2026) con il relativo sostituto:

Campo legacy Campo di sostituzione Note
speed_reading_intervals speed_reading_offsets Utilizza gli offset del misuratore (start_offset, end_offset) anziché le coordinate della polilinea e aggiunge la categoria di velocità TRAFFIC_JAM_HEAVY.
travel_duration.duration_in_seconds duration_in_seconds Appiattito in un campo float di primo livello.
travel_duration.static_duration_in_seconds static_duration_in_seconds Appiattito in un campo float di primo livello.
retrieval_time retrieval_timestamp Formattato come stringa RFC 3339, che gli abbonamenti BigQuery convertono automaticamente in TIMESTAMP.

Trasmettere flussi di dati di itinerari a BigQuery utilizzando Pub/Sub

Puoi configurare una sottoscrizione Pub/Sub per trasmettere in streaming i dati stradali direttamente in una tabella BigQuery. Ciò consente un'archiviazione robusta dei dati e analisi efficaci sulle informazioni sul percorso fornite. Prima di configurare questo tipo di abbonamento, devi creare un set di dati e una tabella adatti nel tuo progetto BigQuery in cui scrivere i dati.

Per istruzioni dettagliate su come creare una sottoscrizione Pub/Sub che scrive in BigQuery, consulta Trasmettere dati in streaming a BigQuery. Crea la sottoscrizione BigQuery per l'argomento codificato in JSON. Quando configuri l'abbonamento, seleziona Utilizza schema tabella e attiva Elimina campi sconosciuti in modo che la pipeline di importazione continui a funzionare senza problemi quando vengono aggiunti nuovi campi. Per memorizzare nuovi campi, ad esempio speed_reading_offsets, aggiungi le colonne corrispondenti alla tabella.

Schema della tabella BigQuery

I messaggi pubblicati nell'argomento Pub/Sub, che possono anche essere scritti nella tabella BigQuery, sono conformi allo schema seguente. Per garantire la compatibilità, devi utilizzare questo schema quando crei la tabella BigQuery di destinazione.

[
  {
    "mode": "NULLABLE",
    "name": "selected_route_id",
    "type": "STRING",
    "description": "Id for selected_route."
  },
  {
    "mode": "NULLABLE",
    "name": "display_name",
    "type": "STRING",
    "description": "User provided name for the route."
  },
  {
    "fields": [
      {
        "mode": "NULLABLE",
        "name": "speed",
        "type": "STRING",
        "description": "Describes the categorized current speed of traffic. Possible values are: \"NORMAL\": Traffic is flowing smoothly, no slowdown is detected. \"SLOW\": Slowdown detected, but no traffic jam formed. \"TRAFFIC_JAM\": Traffic jam detected (groups red and dark red segments; does not include \"TRAFFIC_JAM_HEAVY\")."
      },
      {
        "fields": [
          {
            "mode": "NULLABLE",
            "name": "latitude",
            "type": "NUMERIC"
          },
          {
            "mode": "NULLABLE",
            "name": "longitude",
            "type": "NUMERIC"
          }
        ],
        "mode": "REPEATED",
        "name": "interval_coordinates",
        "type": "RECORD",
        "description": "The geometry for this interval"
      }
    ],
    "mode": "REPEATED",
    "name": "speed_reading_intervals",
    "type": "RECORD",
    "description": "Legacy coordinate-based speed reading intervals. May stop being populated on or after November 9, 2026. Use speed_reading_offsets instead."
  },
  {
    "fields": [
      {
        "mode": "NULLABLE",
        "name": "duration_in_seconds",
        "type": "FLOAT",
        "description": "The duration of travel through the route based on\ncurrent traffic conditions."
      },
      {
        "mode": "NULLABLE",
        "name": "static_duration_in_seconds",
        "type": "FLOAT",
        "description": "The duration of travel through the route without\ntaking traffic conditions into consideration."
      }
    ],
    "mode": "NULLABLE",
    "name": "travel_duration",
    "type": "RECORD",
    "description": "Legacy travel time information. May stop being populated on or after November 9, 2026. Use top-level duration_in_seconds and static_duration_in_seconds instead."
  },
  {
    "fields": [
      {
        "mode": "NULLABLE",
        "name": "seconds",
        "type": "INTEGER",
        "description": "Represents seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. Must be from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59Z inclusive."
      },
      {
        "mode": "NULLABLE",
        "name": "nanos",
        "type": "INTEGER",
        "description": "Non-negative fractions of a second at nanosecond resolution. Negative second values with fractions must still have non-negative nanos values that count forward in time. Must be from 0 to 999,999,999 inclusive."
      }
    ],
    "mode": "NULLABLE",
    "name": "retrieval_time",
    "type": "RECORD",
    "description": "Legacy timestamp when the traffic data was collected. May stop being populated on or after November 9, 2026. Use retrieval_timestamp instead."
  },
  {
    "mode": "NULLABLE",
    "name": "route_geometry",
    "type": "STRING",
    "description": "Contains a geojson polyline representing the optimal route determined based on user's input waypoints"
  },
  {
    "mode": "REPEATED",
    "name": "road_segment_ids",
    "type": "STRING",
    "description": "Road segment place IDs along the route. They follow topological order and are always connected"
  },
  {
    "fields": [
      {
        "mode": "NULLABLE",
        "name": "start_offset",
        "type": "INTEGER",
        "description": "The distance offset from the start of the route in meters for the start of the interval (inclusive)."
      },
      {
        "mode": "NULLABLE",
        "name": "end_offset",
        "type": "INTEGER",
        "description": "The distance offset from the start of the route in meters for the end of the interval (exclusive; equals the start_offset of the subsequent interval)."
      },
      {
        "mode": "NULLABLE",
        "name": "speed",
        "type": "STRING",
        "description": "Describes the categorized current speed of traffic, aligned with the colors in the Google Maps traffic layer. Possible values are: \"NORMAL\" (green): Traffic is flowing smoothly, no slowdown is detected. \"SLOW\" (yellow): Slowdown detected, but no traffic jam formed. \"TRAFFIC_JAM\" (red): Traffic jam detected. \"TRAFFIC_JAM_HEAVY\" (dark red): Heavy traffic jam detected (available as of October 8, 2026)."
      }
    ],
    "mode": "REPEATED",
    "name": "speed_reading_offsets",
    "type": "RECORD",
    "description": "Offset-based speed reading intervals representing traffic density across the route; each interval is demarcated by the distance offset from the start of the route."
  },
  {
    "mode": "NULLABLE",
    "name": "duration_in_seconds",
    "type": "FLOAT",
    "description": "The duration of travel through the route based on current traffic conditions."
  },
  {
    "mode": "NULLABLE",
    "name": "static_duration_in_seconds",
    "type": "FLOAT",
    "description": "The duration of travel through the route without taking traffic conditions into consideration."
  },
  {
    "mode": "NULLABLE",
    "name": "retrieval_timestamp",
    "type": "TIMESTAMP",
    "description": "The time the traffic data was collected."
  }
]