이 제품 또는 기능은 GA 이전 실험 출시 단계 (GA 이전)에 있습니다. GA 이전 제품과 기능은 지원이 제한될 수 있으며, GA 이전 제품과 기능이 변경된 경우 다른 GA 이전 버전과 호환되지 않을 수 있습니다. GA 이전 버전 제품 및 서비스에는 Google Maps Platform 서비스별 약관이 적용됩니다. 자세한 내용은 출시 단계 설명을 참조하세요.

이 페이지는 Cloud Translation API를 통해 번역되었습니다.

AnnotationPaths를 사용하여 경로 주석 가져오기

annotatePaths 메서드를 사용하면 요청한 도로의 동적 교통정보 속성에 대한 주석을 가져올 수 있습니다. 이러한 주석은 고급 운전자 지원 시스템 (ADAS)을 구현하는 데 유용할 수 있습니다.

주석을 가져올 경로 목록과 이러한 경로에 원하는 주석의 유형과 함께 요청을 전송하여 경로 주석을 가져올 수 있습니다. 응답에는 이전에 요청한 주석 처리된 데이터가 있는 경로가 포함됩니다. 응답의 경로는 요청 시 차량이 각 경로를 운전한 것처럼 주석 처리됩니다.

주요 개념

다음 하위 섹션에서는 annotatePaths 메서드를 이해하는 데 필요한 개념을 설명합니다.

경로 및 세그먼트

이 메서드는 차량이 이동할 수 있는 연결된 세그먼트의 시퀀스인 경로의 데이터에 주석을 추가합니다.

다음 다이어그램은 각각 3개의 세그먼트로 구성된 두 개의 경로를 보여줍니다.

각각 3개의 구간으로 구성된 두 개의 경로가 있는 도로 그리드를 보여주는 다이어그램 경로는 동일한 두 세그먼트로 시작하지만 세 번째 세그먼트에서 다른 방향으로 이동합니다.

그림 1. 세그먼트 A, B, C와 세그먼트 A, B, D로 구성된 경로 2로 구성된 경로 1의 다이어그램

경로는 길이가 15km로 제한되며 첫 번째 구간의 시작부터 마지막 구간의 시작까지 측정됩니다. 마지막 구간의 시작 부분이 첫 번째 구간의 시작 부분에서 15km보다 멀리 떨어져 있으면 오류가 발생합니다.

경로의 시작은 항상 가정된 차량 위치이며, 차량에는 여러 위치에서 끝나는 여러 경로가 있을 수 있지만 경로는 다른 위치에서 시작할 수 없습니다.

세그먼트 주석은 속한 경로에 따라 다를 수 있습니다. 두 경로가 동일한 세그먼트 중 일부를 공유하더라도 이러한 세그먼트의 주석이 다를 수 있습니다.

예를 들어 그림 1에서 다음과 같습니다.

경로 1은 다음으로 구성됩니다.
- 세그먼트 A
- 세그먼트 B
- 세그먼트 C
경로 2는 다음으로 구성됩니다.
- 세그먼트 A
- 세그먼트 B
- 세그먼트 D

경로 1에서는 세그먼트 B 다음에 세그먼트 C가, 경로 2에서는 동일한 세그먼트 B 뒤에 다른 세그먼트인 세그먼트 D가 나옵니다.

경로 2에서 우회전할 때 경로 1의 직접 경로보다 더 많은 트래픽이 발생할 수 있기 때문에 경로 1과 경로 2에 대해 반환된 경로 1과 경로 2의 동적 속성이 서로 다를 수 있습니다.

서비스 수준

서비스 수준은 차량 속도, 밀도, 혼잡 및 기타 매개변수를 기반으로 예측된 교통 흐름의 카테고리를 설명하는 데 일반적으로 사용되는 용어입니다. 이 메서드에 사용되고 이 문서에 설명된 서비스 정의 수준은 독점적이며 메서드별로 고유하다는 점에 유의해야 합니다.

다음 목록은 사용되는 서비스 수준을 설명합니다.

서비스 수준	값	설명
`LEVEL_OF_SERVICE_UNSPECIFIED`	0	기본값 이 값은 사용 가능한 예상 트래픽 값이 없음을 의미합니다.
`LEVEL_OF_SERVICE_STOPPED`	1	교통체증이 멈추고 차량이 움직이지 않습니다.
`LEVEL_OF_SERVICE_STOP_AND_GO`	2	차량이 정차했다가 출발하고 차량이 저속으로 움직이다가 곧 멈춥니다.
`LEVEL_OF_SERVICE_SLOW`	3	감속이 예상되고 차량이 천천히 움직이지만 교통체증이 예측되지 않습니다.
`LEVEL_OF_SERVICE_NORMAL`	4	교통량이 보통이며 감속이 예상되지 않습니다.

경로 주석 가져오기

annotatePaths 메서드 (REST)로 HTTP POST 요청을 전송하거나 AnnotatePaths 메서드(gRPC)를 호출하여 경로 주석을 가져올 수 있습니다.

다음 하위 섹션에서는 경로 주석과 REST 참조에 대한 링크를 요청하고 수신하는 데 사용되는 요청 및 응답 본문을 설명합니다.

요청 본문

annotatePaths 메서드 요청 본문에는 다음이 포함됩니다.

Paths: 동적 속성 데이터로 주석을 달기 위해 요청된 경로 (경로 집합)입니다. 이 경로의 모든 경로는 차량이 있는 구간인 동일한 시작 구간을 가져야 합니다. 차량이 첫 번째 구간의 시작 부분에 있는 것으로 간주됩니다. 경로가 동일한 세그먼트에서 시작하지 않으면 오류가 반환됩니다.
- Path: 동적 속성이 요청되는 경로입니다.
- Segments: 경로를 구성하는 세그먼트의 순서가 지정된 목록입니다.
  - Segment: 경로에 속한 세그먼트입니다.
  - Polyline: ID를 찾을 수 없는 경우 구간을 식별하는 데 사용할 수 있는 구간의 다중선입니다. 또한 ID가 동일한 두 세그먼트를 구분하는 데도 사용됩니다. 다중선은 표준 Google Maps Platform 인코딩된 다중선 알고리즘 형식을 사용하여 인코딩됩니다.
  - placeId: 이 도로 구간의 장소 ID로, DirectionalSegment 객체의 placeId 필드와 동일한 값일 수 있습니다.
AnnotationOptions: 입력 경로에 대해 요청된 주석입니다.
- includeLevelOfService: 불리언 필드입니다. true로 설정하면 응답의 세그먼트가 예상 트래픽 값으로 주석 처리됩니다. 자세한 내용은 이 문서의 서비스 수준 섹션을 참조하세요.

요청 요구사항

annotatePaths 메서드의 요청 본문은 다음 요구사항을 따라야 합니다.

경로는 동일한 세그먼트로 시작해야 합니다.
경로는 15km 이하여야 하며, 경로의 마지막 구간은 첫 번째 구간의 시작 부분에서 15km 이내에 시작됩니다.
요청에는 10개 이하의 경로가 포함되어야 합니다.

샘플 요청

다음 예는 annotatePaths 메서드의 요청 본문을 보여줍니다. 이 예시에서는 세 개의 세그먼트로 구성된 경로 하나를 전송하며 서비스 주석 수준을 포함하도록 지정합니다.

paths {
  segments {
    place_id: "ChIJqZ402gQVkFQRcM9QM5EHX1A"
    polyline {
      encoded_polyline: "ojxaHfkviVuAjA_@l@y@jC"
    }
  }
  segments {
    place_id: "ChIJg_9y5AQVkFQRKL3E7_fPM_o"
    polyline {
      encoded_polyline: "_pxaHlsviVg@bB"
    }
  }
  segments {
    place_id: "ChIJle5mqwUVkFQRuhQhpqFyxRM"
    polyline {
      encoded_polyline: "gqxaHpvviV_EtM"
    }
  }
}
annotation_options {
  include_level_of_service: true
}

응답 본문

annotatePaths 메서드 응답 본문에는 다음이 포함됩니다.

annotatedPaths: 요청된 속성으로 주석이 달린 입력의 경로입니다.
- AnnotatedPath: 예측 속성으로 반환된 입력 경로의 사본입니다.
- annotatedSegments: 기본 경로를 형성하는 순서가 지정된 세그먼트 목록으로, 요청된 속성으로 주석이 달립니다.
  - AnnotatedSegment: 동적 데이터 속성으로 주석이 달린 경로를 빌드하는 세그먼트입니다.
  - Segment: 경로에 속한 세그먼트입니다.
    - placeId: 이 도로 구간의 장소 ID로, DirectionalSegment 객체의 placeId 필드와 동일한 값일 수 있습니다.
  - SegmentSpanAttributes: 세그먼트에 할당된 속성입니다. 이러한 속성은 세그먼트가 있는 경로에 따라 다를 수 있습니다. 스팬은 전체 세그먼트를 포함할 수 있습니다. 속성 스팬은 차량 위치에서 경로 끝까지 순서입니다.
    - SegmentSpan: 주석이 적용되는 세그먼트 위치를 설명합니다.
    - LevelOfService: 세그먼트 스팬의 예상 교통량 수준이며, 차량이 구간 시작 부분에 도착할 때 이 구간에서 예상되는 교통량으로 정의됩니다. 자세한 내용은 이 문서의 서비스 수준 섹션을 참조하세요.

샘플 응답

다음 예는 annotatePaths 메서드의 요청 본문을 보여줍니다. 이 예에서는 샘플 요청에서 요청된 하나의 경로에서 서비스 주석 수준을 수신합니다.

annotated_paths {
  annotated_segments {
    segment {
      place_id: "ChIJqZ402gQVkFQRcM9QM5EHX1A"
    }
    segment_span_attributes {
      segment_span {
        start_meters: 0
        end_meters: 142
      }
      level_of_service: LEVEL_OF_SERVICE_NORMAL
    }
  }
  annotated_segments {
    segment {
      place_id: "ChIJg_9y5AQVkFQRKL3E7_fPM_o"
    }
    segment_span_attributes {
      segment_span {
        start_meters: 0
        end_meters: 44
      }
      level_of_service: LEVEL_OF_SERVICE_NORMAL
    }
  }
  annotated_segments {
    segment {
      place_id: "ChIJle5mqwUVkFQRuhQhpqFyxRM"
    }
    segment_span_attributes {
      segment_span {
        start_meters: 0
        end_meters: 206
      }
      level_of_service: LEVEL_OF_SERVICE_NORMAL
    }
  }
}