경로를 따라 검색

search_along_route 도구를 사용하면 LLM이 자연어 쿼리에서 여행 경로를 따라 장소를 찾을 수 있습니다(예: 타호 호수로 가는 길에 있는 전기차 충전소 또는 샌프란시스코와 산호세 사이에 있는 커피숍). 이 도구는 일치하는 장소와 우회로의 장단점을 AI 생성 요약으로 반환합니다. 요약에 인용된 각 장소에 대해 응답에는 장소 ID, 위도/경도 좌표, Google 지도 링크, 필수 저작자 표시, 우회 측정항목도 포함됩니다.

모든 search_along_route 요청은 Pro 옵션이며 Maps Grounding Pro SKU에 따라 청구됩니다.

MCP 서버를 통해 또는 searchAlongRoute REST 메서드로 search_along_route를 호출할 수 있습니다. 이 페이지에서는 요청 옵션, 경로를 지정하는 방법, 응답에 포함된 내용, 요청에 대한 청구 방식을 설명합니다. 전체 스키마는 search_along_route MCP 참조 및 searchAlongRoute REST 참조를 확인하세요.

요청 옵션

LLM은 사용자의 요청과 도구 설명을 기반으로 도구를 호출할 때 이러한 옵션을 설정합니다. 자체 안내를 통해 모델이 사용하는 옵션에 영향을 줄 수 있습니다. Pro 사용량 제어를 참조하세요.

다음 표에서는 search_along_route의 요청 옵션을 설명합니다.

옵션	설명
`text_query`	필수 항목입니다. 경로를 따라 장소를 검색하는 자연어 검색어입니다(예: `ev chargers`, `coffee`, `vegetarian restaurants`).
`retrieval_token`, `route_endpoints`, `encoded_polyline`	필수 항목입니다. 검색할 경로입니다. 각 요청에서 이 세 필드 중 하나를 지정합니다. 경로 지정을 참고하세요.
`travel_mode`	선택사항입니다. 경로 및 우회 경로를 계산하는 데 사용되는 이동 수단: `DRIVE`(기본값), `WALK` 또는 `BICYCLE` `WALK` 및 `BICYCLE`는 `route_endpoints`에서만 지원됩니다. `TRANSIT`는 지원되지 않습니다. `WALK` 경로는 베타 버전이며 명확한 보도 또는 보행자 전용 도로가 누락될 수 있습니다. 앱에 표시하는 모든 도보 경로에 대해 이 경고를 사용자에게 표시해야 합니다.
`routing_preference`	선택사항입니다. 경로 및 우회 시간을 계산하는 데 교통정보 데이터가 사용되는 방식: `ROUTING_PREFERENCE_TRAFFIC_UNAWARE`(기본값) 또는 `ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL` `ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL`는 가능한 경우 실시간 교통 상황을 사용하며 `WALK` 또는 `BICYCLE`에는 지원되지 않습니다.
`include_extended_details`	선택사항입니다. `true`인 경우 요약에는 리뷰, 메뉴 항목, 분위기, 방문자 팁, EV 충전기 사용 가능 여부, 휘발유 가격과 같은 확장된 장소 세부정보가 포함됩니다. 기본값은 `false`입니다.
`language_code`	선택사항입니다. 요약 및 현지화된 우회 거리의 BCP-47 언어 코드입니다(예: `en-US` 또는 `ja`). 기본값은 `en-US`입니다.
`region_code`	선택사항입니다. 사용자의 2자리 CLDR 지역 코드입니다(예: `US` 또는 `CA`). 지역별 장소 이름에 영향을 미치며 관련 법규에 따라 결과에 영향을 미칠 수 있습니다.

경로 지정

각 search_along_route 요청은 상호 배타적인 세 필드 중 하나를 사용하여 경로를 지정해야 합니다. 경로 필드를 두 개 이상 설정하거나 세 개 모두 생략하면 INVALID_ARGUMENT 오류가 반환됩니다.

다음 표에서는 경로를 지정하는 세 가지 방법을 비교합니다.

경로 옵션	입력 형식	지원되는 이동 수단	반환 값 `detourDuration`	사용 시기
`retrieval_token`	이전 `compute_routes` 응답의 `retrievalToken` 문자열(10분 동안 유효)	`DRIVE`	예	상담사가 이미 중간 정류장이 있는 경로를 포함하여 운전 경로에 대해 `compute_routes`를 호출했으며 사용자가 해당 경로를 따라 장소를 요청합니다.
`route_endpoints`	`origin` 및 `destination` 경유지(`address`, `place_id` 또는 `lat_lng`)가 있는 객체	`DRIVE`, `WALK`, `BICYCLE`	예	사용자가 먼저 `compute_routes`를 호출하지 않고 한 번에 두 위치 사이의 장소를 찾도록 요청하거나 경로에서 도보 또는 자전거를 사용합니다.
`encoded_polyline`	운전 경로를 나타내는 인코딩된 다중선 문자열	`DRIVE`	아니요(`localizedDetourDistance`만 반환)	애플리케이션에 이미 Routes API와 같은 다른 소스의 경로 다중선이 있습니다.

`compute_routes` 및 `search_along_route` 체인

compute_routes 요청이 DRIVE 이동 수단을 사용하는 경우 응답의 각 경로에는 retrievalToken 필드가 포함됩니다. 이 토큰은 10분 동안 유효하며 중간 정류장을 포함하여 계산된 경로를 인코딩합니다. 사용자가 해당 경로를 따라 장소를 요청하는 후속 질문을 하면 LLM은 retrievalToken 값을 search_along_route의 retrieval_token로 전달할 수 있습니다.

확장된 장소 세부정보

사용자의 요청에 다음과 같은 경로를 따라 정성적 통계, 실시간 조건 또는 특수 속성이 필요한 경우 include_extended_details를 true로 설정합니다.

리뷰 작성자의 의견: 리뷰 기반 통계, 고객 감정, 의견
구체적인 제품: 메뉴 항목, 요리, 특산품, 음료 또는 비즈니스 하이라이트
분위기: 인테리어, 미적 요소, 분위기 또는 무드
사전 예약 여부, 대기 시간, 장소의 혼잡도, EV 충전기 사용 가능 여부, 휘발유 가격, 주차, 시설 등 실용적인 방문자 팁과 실시간 데이터를 제공합니다.

경로를 따라 주유소, 휴게소, 카페를 위치, 영업시간, 우회 시간별로 찾는 것과 같은 일반적인 검색의 경우 include_extended_details를 false(기본값)로 설정해 둡니다. 세부정보가 확장된 요청은 완료하는 데 시간이 더 오래 걸리지만 모든 search_along_route 요청은 이미 Pro SKU로 청구되므로 추가 요금이 발생하지 않습니다.

예

다음 MCP 요청은 route_endpoints 및 교통정보를 반영한 경로를 사용하여 샌프란시스코와 레이크 타호 사이의 전기자동차 충전소를 검색합니다.

{
  "method": "tools/call",
  "params": {
    "name": "search_along_route",
    "arguments": {
      "text_query": "fast EV chargers with a coffee shop nearby",
      "route_endpoints": {
        "origin": {"address": "San Francisco, CA"},
        "destination": {"address": "Lake Tahoe, CA"}
      },
      "travel_mode": "DRIVE",
      "routing_preference": "ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL",
      "include_extended_details": true
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}

다음 예시에서는 이전 compute_routes 응답의 retrieval_token를 사용합니다.

{
  "method": "tools/call",
  "params": {
    "name": "search_along_route",
    "arguments": {
      "text_query": "coffee shops",
      "retrieval_token": "RETRIEVAL_TOKEN"
    }
  },
  "jsonrpc": "2.0",
  "id": 2
}

RETRIEVAL_TOKEN을 compute_routes에서 반환된 retrievalToken 문자열로 바꿉니다.

다음 예시에서는 첫 번째 요청을 searchAlongRoute REST 메서드로 전송합니다.

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-d '{
  "textQuery": "fast EV chargers with a coffee shop nearby",
  "routeEndpoints": {
    "origin": {"address": "San Francisco, CA"},
    "destination": {"address": "Lake Tahoe, CA"}
  },
  "travelMode": "DRIVE",
  "routingPreference": "ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL",
  "includeExtendedDetails": true
}' \
"https://mapstools.googleapis.com/v1:searchAlongRoute"

API_KEY를 내 API 키로 바꿉니다.

응답

응답에는 다음 필드가 포함됩니다.

summary: 검색 결과 및 우회 장단점에 대한 자연어 요약입니다. results의 항목에 매핑되는 [0]과 같은 0 기반 인용이 포함될 수 있습니다.
results[]: 요약에 언급된 장소의 순위 목록입니다. 각 항목에는 다음이 포함됩니다.
- place: 장소에 관한 세부정보:
  - place: 장소의 리소스 이름이며 형식은 places/{id}입니다.
  - id: 장소 ID입니다. 지도에 장소를 표시하는 등 다른 Google Maps Platform API와 함께 사용할 수 있습니다.
  - location: 장소의 위도/경도 좌표입니다.
  - googleMapsLinks: 장소(placeUrl), 경로(directionsUrl), 리뷰(reviewsUrl), 사진(photosUrl), 리뷰 작성(writeAReviewUrl)에 대한 Google 지도 링크입니다.
  - attribution: 장소와 함께 표시해야 하는 저작자 표시입니다. 저작자 표시 요구사항을 참고하세요.
- detourSummary: 경로를 따라 이 장소에 정차하는 데 필요한 추가 이동 시간 및 거리입니다.
  - localizedDetourDistance: 요청 언어로 형식이 지정된 추가 거리입니다(예: "1.2 mi" 또는 "1.9 km").
  - detourDuration: 추가 이동 시간(기간 문자열, 예: "180s") 경로가 encoded_polyline로 지정된 경우 이 필드는 설정되지 않습니다.
contentToken: 추가 비용 없이 장소 UI 키트를 사용하여 응답에 장소를 표시할 수 있는 에이전트형 데이터 시각화 토큰(프리뷰)입니다. 응답에 장소가 하나 이상 포함된 경우 반환됩니다.

전체 필드 세부정보는 search_along_route 참조를 확인하세요.

결제 및 할당량

각 search_along_route 요청은 Maps Grounding Pro SKU에 따라 청구 가능한 이벤트 하나입니다. include_extended_details를 true로 설정하거나 routing_preference를 ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL로 설정해도 추가 요금이 발생하지 않습니다. 에이전트가 먼저 compute_routes를 호출한 다음 retrieval_token를 search_along_route에 전달하는 경우 각 도구 호출은 별도의 요청으로 청구됩니다.

장소 UI 키트를 사용하여 search_along_route 응답의 장소를 표시하는 경우 에이전트 데이터 시각화 토큰(프리뷰)을 사용하면 해당 장소 UI 키트 요청에 대한 요금이 청구되지 않습니다.

search_along_route 할당량은 프로젝트당 분당 300개의 쿼리입니다. 가격 책정은 기본 가격표 및 인도 가격표를 참조하세요.