구글 지도 Routes API 트래픽 인식 폴리라인: Traffic on Polylines

내비게이션 경로를 지도 위에 표시할 때, 실시간 교통 상황을 반영한 폴리라인을 함께 그릴 수 있다면 사용자에게 더 유용한 정보를 제공할 수 있습니다. Google 지도 Routes API의 TRAFFIC_ON_POLYLINE 기능을 사용하면, 각 폴리라인 구간별로 교통 속도 상태(정상, 느림, 정체)를 함께 받아올 수 있습니다.

 

1. 개요

• 트래픽 인식 폴리라인(Traffic-aware Polyline)은 경로를 구성하는 폴리라인 포인트 사이의 교통 속도 상태를 포함합니다.
• 속도 상태는 NORMAL, SLOW, TRAFFIC_JAM 세 가지 카테고리로 구분됩니다.
• 구간은 폴리라인 포인트 인덱스로 정의되며, 시작 인덱스(포함)와 종료 인덱스(미포함)를 통해 구간별 속도를 나타냅니다.
  
  

2. 요청 방법

1. extraComputations 배열에 "TRAFFIC_ON_POLYLINE"를 포함합니다.
2. travelMode을 DRIVE 또는 TWO_WHEELER로 설정합니다.
3. routingPreference를 TRAFFIC_AWARE 또는 TRAFFIC_AWARE_OPTIMAL로 지정합니다.
4. 응답 필드 마스크(X-Goog-FieldMask)에 routes.travelAdvisory.speedReadingIntervals 및(또는) routes.legs.travelAdvisory.speedReadingIntervals 을 포함합니다.
   
   

3. curl 요청 예시

curl -X POST \
  'https://routes.googleapis.com/directions/v2:computeRoutes' \
  -H 'Content-Type: application/json' \
  -H 'X-Goog-Api-Key: YOUR_API_KEY' \
  -H 'X-Goog-FieldMask: routes.travelAdvisory.speedReadingIntervals,routes.legs.travelAdvisory.speedReadingIntervals' \
  --data-raw '{
    "origin": {
      "location": { "latLng": { "latitude": 37.7749, "longitude": -122.4194 } }
    },
    "destination": {
      "location": { "latLng": { "latitude": 37.7848, "longitude": -122.4090 } }
    },
    "travelMode": "DRIVE",
    "routingPreference": "TRAFFIC_AWARE",
    "extraComputations": ["TRAFFIC_ON_POLYLINE"]
  }'

4. 응답 구조

응답의 speedReadingIntervals 배열에는 다음과 같은 객체들이 포함됩니다:

{
  "startPolylinePointIndex": 2,
  "endPolylinePointIndex": 4,
  "speed": "NORMAL"
}

• startPolylinePointIndex: 구간의 시작 폴리라인 포인트 인덱스(포함)
• endPolylinePointIndex: 구간의 끝 폴리라인 포인트 인덱스(미포함)
• speed: 교통 속도 카테고리 (NORMAL | SLOW | TRAFFIC_JAM)

5. 전체 응답 예시

{
  "routes": [
    {
      "distanceMeters": 1500,
      "duration": "300s",
      "polyline": {
        "encodedPolyline": "abcdEfghIjklMnopQrst..."
      },
      "travelAdvisory": {
        "speedReadingIntervals": [
          { "startPolylinePointIndex": 0, "endPolylinePointIndex": 3, "speed": "NORMAL" },
          { "startPolylinePointIndex": 3, "endPolylinePointIndex": 6, "speed": "SLOW" },
          { "startPolylinePointIndex": 6, "endPolylinePointIndex": 9, "speed": "TRAFFIC_JAM" }
        ]
      },
      "legs": [
        {
          "travelAdvisory": {
            "speedReadingIntervals": [
              { "startPolylinePointIndex": 0, "endPolylinePointIndex": 3, "speed": "NORMAL" },
              { "startPolylinePointIndex": 3, "endPolylinePointIndex": 6, "speed": "SLOW" },
              { "startPolylinePointIndex": 6, "endPolylinePointIndex": 9, "speed": "TRAFFIC_JAM" }
            ]
          }
        }
      ]
    }
  ]
}

6. 활용 팁 및 주의사항

• 폴리라인 디코딩 유틸리티를 사용해 인코딩된 폴리라인과 인덱스를 시각적으로 확인하세요.
• 트래픽 인식 폴리라인 요청은 더 높은 요율로 청구되므로, 꼭 필요한 경우에만 사용하세요.
• 단계별(step-level) 폴리라인에는 트래픽 정보가 포함되지 않습니다. 경로 전체 또는 구간별 정보를 이용하세요.
  
  

Traffic on Polylines 기능을 통해 폴리라인 구간별 교통 속도를 함께 요청하면, 지도 위에 더욱 풍부한 트래픽 정보를 시각화할 수 있습니다.