경로 계산

compute_routes 도구는 지정된 이동 수단에 대해 출발지와 목적지 간의 경로를 반환합니다. 응답에는 경로의 거리와 소요 시간이 포함됩니다. 기본적으로 경로는 실시간 교통정보 없이 계산됩니다. Pro는 실시간 교통정보와 더 많은 경유지가 있는 경로를 고려하는 경로를 추가합니다.

이 페이지에서는 Pro 옵션을 포함한 요청 옵션, 응답에 포함된 내용, 요청에 대한 청구 방식을 설명합니다. 전체 도구 스키마는 compute_routes 참조를 확인하세요.

요청 옵션

옵션	설명
`origin`, `destination`	필수 항목입니다. 각각은 경유지입니다. `address` (인간이 읽을 수 있는 주소 또는 Plus Code), `place_id` 또는 `lat_lng`입니다. 출발지 주소와 목적지 장소 ID와 같이 형식을 혼합할 수 있습니다.
`travel_mode`	이동 수단: `DRIVE` (기본값), `WALK`, `BICYCLE` 또는 `TRANSIT` `WALK` 경로는 베타 버전이며 명확한 보도 또는 보행자 전용 도로가 누락될 수 있습니다. 앱에 표시하는 모든 도보 경로에 대해 이 경고를 사용자에게 표시해야 합니다.
`routing_preference`	경로를 계산하는 데 교통정보 데이터가 사용되는 방식: `ROUTING_PREFERENCE_TRAFFIC_UNAWARE`(기본값) 또는 `ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL`(Pro 옵션) `ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL`는 `WALK` 또는 `BICYCLE`에 지원되지 않습니다. 트래픽 인식 라우팅을 참고하세요.
`intermediate_waypoints`	출발지와 목적지 사이의 정류장 순서입니다. 경로는 지정된 순서대로 경유지를 통과합니다. 요청에는 중간 경유지를 최대 10개까지 포함할 수 있으며, Pro 옵션으로 11~25개까지 포함할 수 있습니다. 25개를 초과하는 요청은 `INVALID_ARGUMENT` 오류를 반환합니다. 대중교통 경로는 중간 경유지를 지원하지 않습니다.
`departure_time` 또는 `arrival_time`	출발지에서 출발하거나 목적지에 도착하는 시간(RFC 3339 타임스탬프)입니다. 최대 1개를 설정합니다. 기본값은 현재 시간에 출발하는 것입니다. `TRANSIT`의 경우 시간은 최대 7일 전 또는 100일 후까지 가능합니다. 다른 이동 수단의 경우 시간은 과거일 수 없으며 최대 365일 전일 수 있습니다.
`compute_alternative_routes`	`true`인 경우 응답에는 추천 경로 외에 대체 경로가 포함됩니다(대체 경로가 있는 경우). 기본값은 `false`입니다.
`include_polyline`	`true`인 경우 응답의 각 경로에 `encodedPolyline`가 포함됩니다. 기본값은 `false`입니다.
`location_bias`	텍스트 경유지가 확인되는 방식에 편향을 적용하는 위도 및 경도입니다(예: 주소의 모호성 해소).

Pro 옵션

두 가지 옵션에서 Pro SKU를 선택합니다. 둘 중 하나 또는 둘 다를 사용하는 요청은 Pro SKU로 청구됩니다.

Pro 옵션	사용 시기
`routing_preference`을 `ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL`으로 설정	사용자가 교통정보, 혼잡도 또는 현재 교통 상황을 반영한 이동 시간에 관해 질문합니다. 트래픽 인식 라우팅을 참고하세요.
11~25`intermediate_waypoints`	경로에 출발지와 목적지 사이에 10개 이상의 경유지가 필요합니다.

이동 모드, 시간, 대체 경로, 다중선, 위치 편향을 포함한 다른 모든 옵션은 Essentials SKU로 청구됩니다.

교통 상황을 반영한 경로 안내

기본적으로 경로는 실시간 교통 상황(ROUTING_PREFERENCE_TRAFFIC_UNAWARE) 없이 계산됩니다. 이 설정은 지연 시간이 가장 짧습니다. 도보 경로 또는 대략적인 계획과 같이 트래픽이 중요하지 않거나 적용되지 않는 요청에 적합합니다.

교통정보를 사용할 수 있는 경우 현재 교통 상황을 반영하여 경로와 소요 시간을 계산하려면 routing_preference를 ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL로 설정합니다. 사용자가 실시간으로 운전하는 데 얼마나 걸리는지 물어볼 때 사용합니다. TRANSIT 경로의 경우 이 설정은 지연 및 취소와 같은 실시간 대중교통 데이터(사용 가능한 경우)를 사용합니다. WALK 또는 BICYCLE 경로에는 지원되지 않습니다. 이러한 요청은 INVALID_ARGUMENT 오류를 반환합니다. 이는 Pro 옵션이므로 요청은 Pro SKU로 청구됩니다. 이 옵션은 지연 시간도 추가합니다.

제한된 정식 버전 기간 동안 프로젝트가 Pro 허용 목록에 없으면 이 옵션은 ROUTING_PREFERENCE_TRAFFIC_UNAWARE로 처리됩니다. 자세한 내용은 제한된 정식 버전 중 Pro 옵션을 참조하세요.

예

다음 요청은 중간 경유지 1개와 인코딩된 다중선이 있는 교통정보를 반영한 운전 경로를 요청합니다. Pro SKU로 청구됩니다.

{
  "method": "tools/call",
  "params": {
    "name": "compute_routes",
    "arguments": {
      "origin": {"address": "Ferry Building, San Francisco, CA"},
      "destination": {"address": "Golden Gate Park, San Francisco, CA"},
      "intermediate_waypoints": [
        {"address": "Palace of Fine Arts, San Francisco, CA"}
      ],
      "travel_mode": "DRIVE",
      "routing_preference": "ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL",
      "include_polyline": true
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}

응답

응답에는 가장 추천하는 것부터 가장 추천하지 않는 것까지 순서대로 정렬된 routes[]가 포함됩니다. compute_alternative_routes이 true가 아니면 하나의 경로만 반환됩니다. 각 경로에는 다음이 포함됩니다.

distanceMeters: 경로의 이동 거리(미터)입니다.
duration: 경로를 이동하는 데 필요한 시간입니다. ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL를 사용하면 소요 시간에 교통 상황이 반영됩니다.
encodedPolyline: include_polyline가 true인 경우 인코딩된 다중선으로 표시되는 경로의 경로입니다. 다른 Google Maps Platform API를 사용하여 지도에 경로를 그리는 데 사용할 수 있습니다.
attribution: 경로와 함께 표시해야 하는 저작자 표시입니다. 저작자 표시 요구사항을 참고하세요.

제한된 정식 버전 기간 중 Pro 옵션

제한된 정식 버전 기간에는 Pro 허용 목록에 있는 프로젝트에서만 Pro 옵션을 사용할 수 있습니다. 프로젝트가 아직 허용 목록에 없는 경우:

ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL는 ROUTING_PREFERENCE_TRAFFIC_UNAWARE로 처리되며 요청은 Essentials SKU로 청구됩니다.
중간 경유지가 10개를 초과하는 요청은 INVALID_ARGUMENT 오류 ('중간 경유지는 최대 10개까지 지원됩니다.')를 반환합니다.

액세스를 요청하려면 제한된 정식 버전 중 Pro 옵션을 참조하세요.

결제 및 할당량

각 compute_routes 요청은 청구 가능한 이벤트 하나입니다.

Pro 옵션을 사용하지 않는 요청은 Essentials SKU에 따라 청구됩니다.
Pro 옵션을 사용하는 요청은 Pro SKU로 청구됩니다. 한 요청에서 두 Pro 옵션을 모두 사용해도 요금은 변경되지 않습니다. Pro 가격 책정은 Essentials, Pro, Google 지도 기반 그라운딩 비교를 참고하세요.

대체 경로, 다중선, 출발 또는 도착 시간, 다른 이동 수단을 요청해도 SKU는 변경되지 않습니다.

compute_routes 할당량은 프로젝트당 분당 300개의 쿼리이며 두 SKU가 공유합니다. 가격 책정은 기본 가격표 및 인도 가격표를 참조하세요.

한도

요청에는 중간 경유지를 최대 25개까지 포함할 수 있습니다. 11~25개는 Pro 옵션입니다. 이보다 많은 요청은 INVALID_ARGUMENT 오류를 반환합니다.
대중교통 경로는 중간 경유지를 지원하지 않습니다. 중간 경유지가 있는 대중교통 요청은 INVALID_ARGUMENT 오류를 반환합니다.
ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL는 도보 또는 자전거 경로에 지원되지 않습니다.
대중교통 경로의 경우 출발 및 도착 시간은 최대 7일 전 또는 100일 후까지 가능합니다. 다른 이동 수단의 경우 과거가 될 수 없으며 최대 365일 전까지 가능합니다.
경유지 좌표는 유효한 지리적 경계 (위도 -90~90, 경도 -180~180) 내에 있어야 합니다.
이 도구는 세부 경로 안내 단계, 구간 또는 대중교통 노선 세부정보를 반환하지 않습니다.