실시간 도로 데이터

실시간 도로 데이터는 선택한 경로의 도로 상황과 이벤트에 관한 최신 업데이트를 제공하여 동적 모니터링과 신속한 대응을 지원합니다. 이 데이터는 BigQuery에서 사용할 수 있는 주기적으로 수집된 데이터와 다르며, 적시에 정보가 필요한 시나리오에 적합합니다.

이 데이터는 지속적으로 스트리밍되며 경로의 이동 시간을 나타내는 이동 시간과 경로를 따라 교통 밀도를 보여주는 속도 판독 간격을 포함합니다.

지원 중단됨: speed_reading_intervals, travel_duration, retrieval_time 필드는 2026년 10월 8일부터 실시간 메시지에 포함되는 speed_reading_offsets, duration_in_seconds, static_duration_in_seconds, retrieval_timestamp 필드로 대체되어 지원 중단됩니다. 2026년 11월 9일부터 지원 중단된 필드가 더 이상 채워지지 않을 수 있습니다. 그 전에 구독자가 새 필드를 읽도록 업데이트하고 이 데이터를 스트리밍하는 BigQuery 테이블에 새 열을 추가하세요.

실시간 도로 데이터에 액세스하려면 계약에 실시간 운영 패키지가 포함되어 있어야 합니다.

이동 시간 및 속도 읽기 간격 Pub/Sub 구독 만들기

생성된 모든 경로의 실시간 데이터를 구독할 수 있는 전용 Google Cloud Pub/Sub 주제가 제공됩니다.

다음 코드 샘플은 바이너리 인코딩을 사용하는 주제의 형식을 보여줍니다.

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

JSON 인코딩을 사용하는 다른 주제 (-json 접미사)도 제공됩니다. 실시간 데이터 메시지를 수신하려면 제공된 Pub/Sub 주제를 구독해야 합니다. Cloud Pub/Sub 주제에서 메시지를 구독하고 사용하는 방법에 대한 간략한 개요는 주제 구독을 참고하세요.

이동 시간 및 속도 읽기 간격 스키마

각 실시간 데이터 메시지에는 다음과 같은 데이터가 포함됩니다.

• duration_in_seconds, static_duration_in_seconds, speed_reading_offsets (오프셋 기반 속도 읽기 간격), retrieval_timestamp과 같은 도로 세부정보
• 경로 식별자(예: selected_route_id 및 display_name)

각 메시지는 다음 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;
}

오프셋 기반 속도 읽기 간격 및 필드 마이그레이션

2026년 10월 8일부터 속도 읽기 간격은 오프셋 기반 speed_reading_offsets 필드에 제공되며, 각 간격은 경로 시작부터 미터 단위로 start_offset (포함) 및 end_offset (제외)로 구분되고 네 번째 속도 카테고리 TRAFFIC_JAM_HEAVY가 포함됩니다. 속도 카테고리 및 간격 형식에 관한 자세한 내용은 속도 읽기 간격을 참고하세요.

다음 표에서는 각 기존 Pub/Sub 필드 (2026년 11월 9일 이후에 채워지지 않을 수 있음)를 대체 필드에 매핑합니다.

기존 필드	대체 필드	참고
speed_reading_intervals	speed_reading_offsets	폴리라인 좌표 대신 미터 오프셋 (start_offset, end_offset)을 사용하고 TRAFFIC_JAM_HEAVY 속도 카테고리를 추가합니다.
travel_duration.duration_in_seconds	duration_in_seconds	최상위 float 필드로 평면화되었습니다.
travel_duration.static_duration_in_seconds	static_duration_in_seconds	최상위 float 필드로 평면화되었습니다.
retrieval_time	retrieval_timestamp	RFC 3339 문자열로 형식이 지정되며, BigQuery 구독에서 자동으로 TIMESTAMP로 변환합니다.

Pub/Sub를 사용하여 경로 데이터를 BigQuery로 스트리밍

도로 데이터를 BigQuery 테이블로 직접 스트리밍하도록 Pub/Sub 구독을 구성할 수 있습니다. 이를 통해 강력한 데이터 스토리지가 가능하며 제공된 경로 정보에 대한 강력한 분석이 가능합니다. 이 유형의 구독을 설정하기 전에 데이터를 쓸 적절한 데이터 세트와 테이블을 BigQuery 프로젝트에 만들어야 합니다.

BigQuery에 쓰는 Pub/Sub 구독을 만드는 방법에 관한 자세한 안내는 BigQuery로 데이터 스트리밍을 참고하세요. JSON으로 인코딩된 주제에 BigQuery 구독을 만듭니다. 구독을 구성할 때 테이블 스키마 사용을 선택하고 알 수 없는 필드 삭제를 사용 설정하여 새 필드가 추가될 때 수집 파이프라인이 원활하게 계속 실행되도록 합니다. speed_reading_offsets과 같은 새 필드를 저장하려면 테이블에 해당 열을 추가합니다.

BigQuery 테이블 스키마

Pub/Sub 주제에 게시된 메시지는 BigQuery 테이블에 기록될 수도 있으며 다음 스키마를 준수합니다. 호환성을 보장하려면 대상 BigQuery 테이블을 만들 때 이 스키마를 사용해야 합니다.

[
  {
    "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."
  }
]