경로 다중선 요청

유럽 경제 지역 (EEA) 개발자

computeRoutes 메서드 (REST)와 ComputeRoutes 메서드 (gRPC)는 모두 응답의 일부로 다중선으로 표시된 경로를 반환합니다. 이러한 API는 두 가지 유형의 폴리라인을 반환합니다.

  • 기본 다중선 (기본값): 경로를 나타내지만 다중선에 교통정보가 삽입되어 있지 않습니다. 기본 폴리라인을 반환하는 요청은 Routes Basic 요금으로 청구됩니다. Routes API의 결제에 대해 자세히 알아보기

  • 교통 상황 인식 폴리라인은 경로를 따라 교통 상황에 관한 정보를 포함합니다. 교통상황은 폴리라인의 특정 구간에 적용되는 속도 카테고리 (NORMAL, SLOW, TRAFFIC_JAM)로 표현됩니다. 교통 상황을 고려한 폴리라인 요청에는 Routes Preferred 요금이 청구됩니다. Routes API의 결제에 대해 자세히 알아보세요. 자세한 내용은 폴리라인 품질 구성을 참고하세요.

폴리라인에 대한 자세한 내용은 다음을 참고하세요.

경로, 구간 또는 단계의 기본 폴리라인 요청

다중선은 Polyline (REST) 또는 Polyline (gRPC) 객체로 표시됩니다. 경로, 구간, 단계 수준에서 대답에 폴리라인을 반환할 수 있습니다.

응답 필드 마스크를 사용하여 반환할 폴리라인을 지정합니다.

  • 경로 수준에서, 응답 필드 마스크에 routes.polyline를 포함하여 응답에 폴리라인을 반환합니다.

  • 구간 수준에서 routes.legs.polyline를 포함하여 경로의 각 구간에 대한 폴리라인을 응답에 반환합니다.

  • 단계 수준에서 routes.legs.steps.polyline를 포함하여 구간의 각 단계에 대한 응답에 폴리라인을 반환합니다.

예를 들어 전체 경로, 각 구간, 각 구간의 각 단계에 대한 폴리라인을 반환하려면 다음을 실행합니다.

curl -X POST -d '{
  "origin":{
    "address": "1600 Amphitheatre Parkway, Mountain View, CA"
  },
  "destination":{
    "address": "24 Willie Mays Plaza, San Francisco, CA 94107"
  },
  "travelMode": "DRIVE"
}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline,routes.legs.polyline,routes.legs.steps.polyline' \
'https://routes.googleapis.com/directions/v2:computeRoutes'

이 요청은 경로의 폴리라인, 경로의 각 구간, 구간의 각 단계를 포함하는 다음 응답을 반환합니다.

{
  "routes": [
    {
      "legs": [
        {
          "polyline": {
              "encodedPolyline": "ipkcFfich...@Bs@?A?O?SD{A@o@B}@I?qA?_AA_@@_@?"
          }
        },
          "steps": [
              {
                  "polyline": {
                      "encodedPolyline": "kclcF...@sC@YIOKI"
                  }
              },
              {
                  "polyline": {
                      "encodedPolyline": "wblcF~...SZSF_@?"
                  }
              },
              ...
      ],
      "distanceMeters": 56901,
      "duration": "2420s",
      "polyline": {
        "encodedPolyline": "ipkcFfich...@Bs@?A?O?SD{A@o@B}@I?qA?_AA_@@_@?"
      }
    }
  ]
}

이 요청에는 출발지와 목적지만 포함되므로 반환된 경로에는 구간이 하나만 포함됩니다. 따라서 구간과 경로의 다중선이 동일합니다.

요청에 중간 경유지를 추가하면 반환된 경로에 다음 두 구간이 포함됩니다.

curl -X POST -d '{
  "origin":{
    "address": "1600 Amphitheatre Parkway, Mountain View, CA"
  },
  "destination":{
    "address": "24 Willie Mays Plaza, San Francisco, CA 94107"
  },
  "intermediates": [
    { "address": "450 Serra Mall, Stanford, CA 94305, USA"},
  ],
  "travelMode": "DRIVE",
}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline,routes.legs.polyline' \
'https://routes.googleapis.com/directions/v2:computeRoutes'

이 요청은 각각 고유한 폴리라인이 있는 두 구간과 전체 경로의 폴리라인을 반환합니다.

{
  "routes": [
    {
      "legs": [
        {
          "polyline": {
            "encodedPolyline": "kclcFfqchV?A...?I@G?GAECCCEKICBAFG"
          }
          "steps": [
            {
                "polyline": {
                    "encodedPolyline": "kclcFfqch...YIOKI"
                }
            },
        ...
        },
        {
          "polyline": {
            "encodedPolyline": "ojmcFtethV?K...QOYQOGA?_@MUG[Ga@G"
          }
          "steps": [
            {
                "polyline": {
                    "encodedPolyline": "uypeFbo`jVgJq...PoBiC"
                }
            },
        ...
        }
      ],
      "distanceMeters": 68403,
      "duration": "3759s",
      "polyline": {
          "encodedPolyline": "kclcFfqchV?A?CBKF[Ha...?GAECCCEKICBAFGJEBE"
      }
    }
  ]
}

다중선 품질

폴리라인의 품질은 다음 용어로 설명할 수 있습니다.

  • 포인트의 부동 소수점 정밀도

    지점은 단일 정밀도 부동 소수점 형식으로 표현되는 위도 및 경도 값으로 지정됩니다. 이 방법은 정확하게 표현할 수 있는 작은 값에는 적합하지만 부동 소수점 반올림 오류로 인해 값이 증가할수록 정밀도가 감소합니다.

    computeRoutes 메서드 (REST) 및 ComputeRoutes에서 이는 polylineEncoding에 의해 제어됩니다.

  • 폴리라인을 구성하는 점의 수

    포인트가 많을수록 폴리라인이 더 부드러워집니다 (특히 곡선에서).

    computeRoutes 메서드 (REST) 및 ComputeRoutes에서 이는 polylineQuality에 의해 제어됩니다.

다중선 인코딩 유형 구성

polylineEncoding 요청 옵션을 사용하여 폴리라인 유형을 제어합니다. polylineEncoding 속성은 다중선이 ENCODED_POLYLINE (기본값)로 인코딩되는지 여부를 제어합니다. 즉, 인코딩된 다중선 알고리즘 형식이 사용되거나 GEO_JSON_LINESTRING로 인코딩됩니다. 즉, GeoJSON LineString 형식이 사용됩니다.

예를 들어 요청 본문에서 다음과 같이 지정할 수 있습니다.

curl -X POST -d '{
  "origin":{
    "address": "1600 Amphitheatre Parkway, Mountain View, CA"
  },
  "destination":{
    "address": "24 Willie Mays Plaza, San Francisco, CA 94107"
  },
  "travelMode": "DRIVE",
  "polylineEncoding": "ENCODED_POLYLINE"
}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline,routes.legs.polyline' \
'https://routes.googleapis.com/directions/v2:computeRoutes'

다중선 품질 구성

polylineQuality은 폴리라인의 품질을 HIGH_QUALITY 또는 OVERVIEW (기본값)로 지정합니다. OVERVIEW를 사용하면 폴리라인이 적은 수의 점을 사용하여 구성되며 HIGH_QUALITY보다 요청 지연 시간이 짧습니다.

예를 들어 요청 본문에서 다음과 같이 지정할 수 있습니다.

{
  "origin":{
    "location":{
      "latLng":{
        "latitude": 37.419734,
        "longitude": -122.0827784
      }
    }
  },
  "destination":{
    "location":{
      "latLng":{
        "latitude": 37.417670,
        "longitude": -122.079595
      }
    }
  },
  "travelMode": "DRIVE",
  "routingPreference": "TRAFFIC_AWARE",
  "polylineQuality": "HIGH_QUALITY",
  "polylineEncoding": "ENCODED_POLYLINE",
  "departureTime": "2023-10-15T15:01:23.045123456Z",
  ...
}

교통 상황을 고려한 다중선 요청

위의 예에서는 모두 기본 다중선(교통 정보가 없는 다중선)을 반환합니다. 또한 경로 및 경로의 각 구간에 대한 교통정보를 폴리라인에 포함하도록 요청할 수도 있습니다.

교통 상황을 고려한 다중선에는 경로를 따라 교통 상황에 관한 정보가 포함됩니다. 교통 상황은 응답 폴리라인의 지정된 간격에 대한 속도 카테고리(NORMAL, SLOW, TRAFFIC_JAM)로 표현됩니다. 간격은 시작 (포함) 및 종료 (제외) 폴리라인 점의 색인으로 정의됩니다.

예를 들어 다음 응답은 폴리라인 포인트 2와 4 사이의 NORMAL 트래픽을 보여줍니다.

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

교통 상황을 고려한 폴리라인을 계산하도록 요청하려면 요청에서 다음 속성을 설정하세요.

  • extraComputations 배열 필드를 TRAFFIC_ON_POLYLINE로 설정하여 트래픽 계산을 사용 설정합니다.

  • travelMode을 DRIVE 또는 TWO_WHEELER로 설정합니다. 다른 이동 수단을 요청하면 오류가 반환됩니다.

  • 요청에서 TRAFFIC_AWARE 또는 TRAFFIC_AWARE_OPTIMAL 라우팅 환경설정을 지정합니다. 자세한 내용은 품질과 지연 시간 구성을 참고하세요.

  • 응답 속성을 반환하도록 지정하는 응답 필드 마스크를 설정합니다.

    • 경로 수준에서 응답 필드 마스크에 routes.travelAdvisory를 포함하여 응답에 모든 여행 정보를 반환합니다. 트래픽 정보만 반환하려면 routes.travelAdvisory.speedReadingIntervals를 지정합니다.

    • 구간 수준에서 routes.legs.travelAdvisory를 포함하여 경로의 각 구간에 대한 응답으로 모든 여행 정보를 반환합니다. 트래픽 정보만 반환하려면 routes.legs.travelAdvisory.speedReadingIntervals를 지정합니다.

curl -X POST -d '{
  "origin":{
    "address": "1600 Amphitheatre Parkway, Mountain View, CA"
  },
  "destination":{
    "address": "24 Willie Mays Plaza, San Francisco, CA 94107"
  },
  "travelMode": "DRIVE",
  "extraComputations": ["TRAFFIC_ON_POLYLINE"],
  "routingPreference": "TRAFFIC_AWARE_OPTIMAL"
}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline,routes.legs.polyline,routes.travelAdvisory,routes.legs.travelAdvisory' \
'https://routes.googleapis.com/directions/v2:computeRoutes'

교통 상황을 고려한 폴리라인의 응답 예

응답에서 교통 데이터는 다중선으로 인코딩되며 RouteLegTravelAdvisory 객체 (각 구간) 및 RouteTravelAdvisory 객체 (경로) 유형의 travelAdvisory 필드에 포함됩니다.

예를 들면 다음과 같습니다.

{
  "routes": [
    {
      "legs": {
        "polyline": {
          "encodedPolyline": "}boeF~zbjVAg@EmB`GWHlD"
        },
        // Traffic data for the leg.
        "travelAdvisory": {
          "speedReadingIntervals": [
            {
              "endPolylinePointIndex": 1,
              "speed": "NORMAL"
            },
            {
              "startPolylinePointIndex": 1,
              "endPolylinePointIndex": 2,
              "speed": "SLOW"
            },
            {
              "startPolylinePointIndex": 2,
              "endPolylinePointIndex": 4,
              "speed": "NORMAL"
            }
          ] 
        }
      },
      "polyline": {
        "encodedPolyline": "}boeF~zbjVAg@EmB`GWHlD"
      },
      // Traffic data for the route.
      "travelAdvisory": {
        "speedReadingIntervals": [
          {
            "endPolylinePointIndex": 1,
            "speed": "NORMAL"
          },
          {
            "startPolylinePointIndex": 1,
            "endPolylinePointIndex": 2,
            "speed": "SLOW"
          },
          {
            "startPolylinePointIndex": 2,
            "endPolylinePointIndex": 4,
            "speed": "NORMAL"
          }
        ] 
      }
    }
  ]
}

RouteTravelAdvisory와 RouteLegTravelAdvisory 모두 교통량 정보를 포함하는 speedReadingIntervals라는 배열 필드가 포함됩니다. 배열의 각 객체는 SpeedReadingInterval (REST) 또는 SpeedReadingInterval(gRPC) 객체로 표시됩니다.

SpeedReadingInterval 객체에는 NORMAL, SLOW, TRAFFIC_JAM과 같은 경로 구간의 속도 읽기가 포함됩니다. 전체 객체 배열은 중복 없이 경로의 전체 다중선을 포함합니다. 지정된 간격의 시작점은 이전 간격의 끝점과 동일합니다.

모든 인터벌은 startPolylinePointIndex, endPolylinePointIndex, 해당 속도 카테고리로 설명됩니다. 인터벌 내 시작 색인이 없으면 proto3 관행에 따라 색인 0에 해당합니다.

startPolylinePointIndex 및 endPolylinePointIndex 값이 항상 연속되는 것은 아닙니다. 예를 들면 다음과 같습니다.

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

이 경우 트래픽 조건은 색인 2부터 색인 4까지 동일했습니다.

Maps SDK로 교통 상황을 고려한 폴리라인 렌더링

폴리라인 구간에 따른 맞춤 색상, 획, 패턴 등 Google Maps SDK에서 제공하는 다양한 기능을 사용하여 지도에 교통 상황을 인식하는 폴리라인을 표시하는 것이 좋습니다. 폴리라인 사용에 관한 자세한 내용은 Android용 폴리라인 기능 및 iOS용 폴리라인 기능을 참고하세요.

다중선 렌더링 예

Maps SDK 사용자는 속도 카테고리와 다중선 렌더링 스키마 간의 맞춤 매핑 로직을 정의할 수 있습니다. 예를 들어 '보통' 속도를 지도에 두꺼운 파란색 선으로 표시하고 '느림' 속도를 두꺼운 주황색 선으로 표시할 수 있습니다.

다음 스니펫은 멜버른에서 퍼스까지의 최단 거리 보간을 파란색의 굵은 다중선으로 추가합니다. 자세한 내용은 모양 맞춤설정(Android) 및 폴리라인 맞춤설정 (iOS)을 참고하세요.

Android

자바

Polyline line = map.addPolyline(new PolylineOptions()
    .add(new LatLng(-37.81319, 144.96298), new LatLng(-31.95285, 115.85734))
    .width(25)
    .color(Color.BLUE)
    .geodesic(true));

Kotlin

val line: Polyline = map.addPolyline(
  PolylineOptions()
    .add(LatLng(-37.81319, 144.96298), LatLng(-31.95285, 115.85734))
    .width(25f)
    .color(Color.BLUE)
    .geodesic(true)
)

iOS

Objective-C

GMSMutablePath *path = [GMSMutablePath path];
[path addLatitude:-37.81319 longitude:144.96298];
[path addLatitude:-31.95285 longitude:115.85734];
GMSPolyline *polyline = [GMSPolyline polylineWithPath:path];
polyline.strokeWidth = 10.f;
polyline.strokeColor = .blue;
polyline.geodesic = YES;
polyline.map = mapView;

Swift

let path = GMSMutablePath()
path.addLatitude(-37.81319, longitude: 144.96298)
path.addLatitude(-31.95285, longitude: 115.85734)
let polyline = GMSPolyline(path: path)
polyline.strokeWidth = 10.0
polyline.geodesic = true
polyline.map = mapView

경로 따라 검색에서 인코딩된 다중선 사용

Places API 텍스트 검색을 사용하여 계산된 경로를 따라 검색합니다. Routes API Compute Routes에서 미리 계산된 경로의 인코딩된 폴리라인을 텍스트 검색 요청에 전달합니다. 그러면 응답에 검색 기준과 일치하고 지정된 경로 근처에 있는 장소가 포함됩니다. 자세한 내용은 경로를 따라 검색을 참고하세요.

예를 들어 출발지와 목적지 사이의 경로에 있는 카페를 반환하려면 다음을 실행합니다.

Node.js

const API_KEY = 'YOUR_API_KEY';
const routes_service = 'https://routes.googleapis.com/directions/v2:computeRoutes';
const textSearch_service = 'https://places.googleapis.com/v1/places:searchText';



function init(){
    const routes_request = {
        "origin":{
            "address": "1600 Amphitheatre Parkway, Mountain View, CA"
        },
        "destination":{
            "address": "24 Willie Mays Plaza, San Francisco, CA 94107"
        },
        "travelMode": "DRIVE"
    };
    const textSearch_request = {
        "textQuery": "cafe",
        "searchAlongRouteParameters": {
            "polyline": {
                "encodedPolyline": ""
            }
        }
    };
    fetchResources(routes_service,routes_request).then(routes => {
        textSearch_request.searchAlongRouteParameters.polyline.encodedPolyline = routes.routes[0].polyline.encodedPolyline;
        fetchResources(textSearch_service,textSearch_request).then(places => {
            console.log(places);
        });
    });
}
async function fetchResources(resource,reqBody){
    const response = await fetch(resource, {
        method: 'POST',
        body: JSON.stringify(reqBody),
        headers: {
            'Content-Type': 'application/json',
            'X-Goog-Api-Key': API_KEY,
            'X-Goog-FieldMask': '*'
        }
    });
    const responseJSON = await response.json();
    return responseJSON;
}
init();