MCP Tools Reference: mapstools.googleapis.com

도구: search_along_route

사용자가 이동 경로를 따라 장소, 비즈니스 또는 관심 장소를 찾으려고 할 때 이 도구를 호출합니다(예: '타호로 가는 길에 있는 주유소', '샌프란시스코와 산호세 사이의 커피숍'). 이 도구를 호출하면 search_places보다 비용이 더 많이 들므로 경로가 아닌 단일 위치 근처를 검색할 때는 search_places를 대신 사용하세요.

입력 요구사항(중요):

  1. text_query(문자열 - 필수): 경로를 따라 검색할 항목에 대한 자연어 설명입니다.

    • 예시: 'ev chargers', 'coffee', 'vegetarian restaurants', 'rest stops'.

  2. 경로 사양(필수 - 다음 중 하나만 제공):

    • retrieval_token(문자열): DRIVE 경로에 대한 이전 compute_routes 호출에서 반환된 retrieval_token입니다. 경로가 이미 계산된 경우 이 방법을 사용하는 것이 좋습니다. 토큰은 10분 동안 유효합니다.
    • route_endpoints(객체): 경로의 origin 및 destination입니다. 각각은 address, lat_lng 또는 place_id 중 하나를 사용하여 제공해야 합니다.
      • 예: {"route_endpoints": {"origin": {"address": "San Francisco, CA"}, "destination": {"address": "Lake Tahoe, CA"}}}
    • encoded_polyline(문자열): DRIVE 경로를 나타내는 인코딩된 다중선입니다.

  3. travel_mode(enum - 선택사항): DRIVE(기본값), WALK 또는 BICYCLE WALK 및 BICYCLE는 route_endpoints에서만 지원됩니다. TRANSIT는 지원되지 않습니다.

  4. routing_preference(enum - 선택사항):

    • ROUTING_PREFERENCE_TRAFFIC_UNAWARE(기본값): 실시간 교통정보 없이 경로와 우회 경로를 계산합니다. 가장 짧은 지연 시간
    • ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL: 가능한 경우 실시간 교통 상황을 사용합니다. WALK 또는 BICYCLE에는 지원되지 않습니다. 사용자가 교통정보, 혼잡도 또는 교통 상황에 따른 우회 시간에 대해 문의하는 경우에만 이 값을 설정합니다. 지연 시간이 길어집니다.

  5. include_extended_details(불리언 - 선택사항): 요청에 정성적 리뷰 인사이트, 특정 메뉴 항목 또는 제공 서비스, 분위기, 방문자 팁 또는 혼잡도, EV 충전기 사용 가능 여부, 휘발유 가격 또는 기타 풍부한 정성적 세부정보가 필요한 경우에만 true로 설정합니다. 기본값은 false입니다. 사용 설정하면 지연 시간이 늘어날 수 있습니다.

  6. language_code(문자열 - 선택사항): 결과 요약 및 장소 세부정보의 언어입니다(예: en, ja, en-US). 기본값은 en-US입니다.

  7. region_code(문자열 - 선택사항): 사용자의 유니코드 CLDR 지역 코드입니다(예: US, CA).

도구 호출 안내:

  • 각 결과에는 해당 장소에 정차하여 발생하는 추가 거리(localized_detour_distance)를 설명하는 detour_summary(사용 가능한 경우)가 포함되며, 경로가 encoded_polyline로 지정되지 않은 경우 추가 시간(detour_duration)이 포함됩니다. 이를 사용하여 옵션을 비교합니다.
  • 응답 summary에는 results의 항목을 참조하는 0 기반 인용(예: '[0]')이 포함될 수 있습니다.
  • 그라운딩된 출력은 가능한 경우 각 results[].place의 attribution 필드를 사용하여 소스에 기여해야 합니다.

다음 코드 샘플은 curl를 사용하여 search_along_route MCP 도구를 호출하는 방법을 보여줍니다.

curl 요청 
curl --location 'https://mapstools.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "search_along_route",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

입력 스키마

SearchAlongRoute의 요청 메시지입니다.

SearchAlongRouteRequest

JSON 표현 
{
  "textQuery": string,
  "languageCode": string,
  "regionCode": string,
  "routingPreference": enum (RoutingPreference),
  "includeExtendedDetails": boolean,
  "travelMode": enum (RouteTravelMode),

  // Union field route_spec can be only one of the following:
  "encodedPolyline": string,
  "retrievalToken": string,
  "routeEndpoints": {
    object (RouteEndpoints)
  }
  // End of list of possible types for union field route_spec.
}
필드
textQuery

string

필수 항목입니다. 자연어 검색어(예: 'EV 충전기', '커피')입니다.
languageCode

string

선택사항입니다. 요약 및 장소 세부정보의 언어입니다. 기본값은 'en-US'입니다.
regionCode

string

선택사항입니다. 위치의 국가/지역 코드(CLDR)입니다(예: 'US').
routingPreference

enum (RoutingPreference)

선택사항입니다. 교통정보 데이터가 사용되는 방식을 지정하는 선택적 경로 환경설정입니다. 기본값은 TRAFFIC_UNAWARE입니다.
includeExtendedDetails

boolean

선택사항입니다. 응답에 확장된 장소 세부정보를 포함합니다.

사용자 요청에 풍부한 정성적 인사이트, 실시간 역학 또는 전문 항목 속성이 필요한 경우 이 필드를 true로 설정합니다. - 정성적 리뷰, 고객 감정, 의견 - 메뉴 항목, 요리, 특산품, 음료 또는 비즈니스 하이라이트와 같은 특정 제품 또는 서비스 - 정성적 분위기, 인테리어 장식, 미적 요소, 분위기 또는 무드 - 실시간 데이터 및 전문 시설 사양, 방문자 정책/팁, 대기 시간

표준 탐색 검색(예: 요리, 매장 유형), 위치/주소 조회, 연락처 정보, 영업시간, 표준 메타데이터/편의시설의 경우 false(기본값)로 둡니다.

이 필드를 사용 설정하면 지연 시간이 길어질 수 있습니다.
travelMode

enum (RouteTravelMode)

선택사항입니다. 경로 및 우회 경로를 계산하는 데 사용되는 이동 수단을 지정합니다. 기본값은 DRIVE입니다. WALK 및 BICYCLE는 route_endpoints에서만 지원됩니다. TRANSIT는 지원되지 않습니다.
통합 필드 route_spec. 경로 사양: 기존 경로, 경로 토큰 또는 출발지/목적지 엔드포인트입니다. route_spec은 다음 중 하나여야 합니다.
encodedPolyline

string

경로를 나타내는 인코딩된 다중선 문자열입니다. https://developers.google.com/maps/documentation/utilities/polylinealgorithm을 참고하세요.
retrievalToken

string

경로를 나타내는 이전 ComputeRoutes 호출에서 반환된 검색 토큰입니다.
routeEndpoints

object (RouteEndpoints)

명시적 경로 엔드포인트(출발지 및 목적지)

RouteEndpoints

JSON 표현 
{
  "origin": {
    object (Waypoint)
  },
  "destination": {
    object (Waypoint)
  }
}
필드
origin

object (Waypoint)

필수 항목입니다. 출발지(주소, 장소 ID 또는 지리적 좌표)입니다.
destination

object (Waypoint)

필수 항목입니다. 도착 지점(주소, 장소 ID 또는 지리적 좌표)입니다.

경유지

JSON 표현 
{

  // Union field location_type can be only one of the following:
  "latLng": {
    object (LatLng)
  },
  "placeId": string,
  "address": string
  // End of list of possible types for union field location_type.
}
필드
통합 필드 location_type. 위치를 나타내는 다양한 방법 location_type은 다음 중 하나여야 합니다.
latLng

object (LatLng)

지리적 좌표를 사용하여 지정된 지점입니다.
placeId

string

경유지와 연결된 장소 ID입니다.
address

string

사람이 읽을 수 있는 주소 또는 Plus Code입니다. 자세한 내용은 https://plus.codes를 참고하세요.

LatLng

JSON 표현 
{
  "latitude": number,
  "longitude": number
}
필드
latitude

number

위도입니다. 범위는 [-90.0, +90.0]입니다.
longitude

number

경도입니다. 범위는 [-180.0, +180.0]입니다.

RoutingPreference

경로를 계산할 때 고려해야 할 요소를 지정하는 값 집합입니다.

열거형
ROUTING_PREFERENCE_UNSPECIFIED 라우팅 환경설정이 지정되지 않았습니다. 기본값은 ROUTING_PREFERENCE_TRAFFIC_UNAWARE입니다.
ROUTING_PREFERENCE_TRAFFIC_UNAWARE 실시간 교통 상황을 고려하지 않고 경로를 계산합니다. 교통 상황이 중요하지 않거나 적용되지 않는 경우에 적합합니다. 이 값을 사용하면 지연 시간이 가장 짧습니다.
ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL

교통정보 데이터를 사용할 수 있는 경우 실시간 교통 상황을 고려하여 경로를 계산합니다. TRANSIT의 경우 지연 및 취소와 같은 실시간 대중교통 데이터가 있으면 이를 사용합니다.

이 값은 Pro 등급을 트리거하고 더 높은 청구 비용과 지연 시간을 발생시킵니다.

RouteTravelMode

이동 수단을 지정하는 데 사용되는 값 집합입니다.

열거형
ROUTE_TRAVEL_MODE_UNSPECIFIED 지정된 이동 수단이 없습니다. 기본값은 DRIVE입니다.
DRIVE 승용차로 이동합니다.
WALK 도보로 이동합니다. 참고: WALK 경로는 베타 버전이며 명확한 보도 또는 보행자 전용 도로가 누락될 수 있습니다. 앱에 표시하는 모든 도보 경로에 대해 이 경고를 사용자에게 표시해야 합니다.
BICYCLE 자전거로 이동합니다.
TRANSIT 대중교통으로 이동합니다.

출력 스키마

SearchAlongRoute의 응답 메시지입니다.

SearchAlongRouteResponse

JSON 표현 
{
  "results": [
    {
      object (Result)
    }
  ],
  "summary": string,
  "contentToken": string
}
필드
results[]

object (Result)

출력 전용입니다. 경로를 따라 발견된 검색 결과의 순위 목록입니다.
summary

string

출력 전용입니다. 검색 결과 및 우회로 장단점을 자연어로 요약합니다. results 목록의 해당 항목을 참조하는 0 기반 인용(예: '[0]', '[1]')이 포함될 수 있습니다.
contentToken

string

출력 전용입니다. 검색 컨텍스트를 캡슐화하는 암호화된 토큰으로, Google 지도 시각적 렌더링 서비스, SDK 또는 지도 에이전트 UI 툴킷(A2UI)에 전달하여 반환된 검색 결과에 대한 대화형 UI 구성요소를 표시할 수 있습니다.

결과

JSON 표현 
{
  "place": {
    object (PlaceView)
  },
  "detourSummary": {
    object (DetourSummary)
  }
}
필드
place

object (PlaceView)

출력 전용입니다. 경로를 따라 발견된 장소에 대한 세부정보입니다.
detourSummary

object (DetourSummary)

출력 전용입니다. 이 장소를 경로의 중간 경유지로 추가하여 발생한 우회 측정항목입니다. 우회 측정항목을 계산할 수 없는 경우 생략되거나 비어 있습니다.

PlaceView

JSON 표현 
{
  "place": string,
  "id": string,
  "googleMapsLinks": {
    object (GoogleMapsLinks)
  },
  "attribution": {
    object (Attribution)
  },

  // Union field _location can be only one of the following:
  "location": {
    object (LatLng)
  }
  // End of list of possible types for union field _location.
}
필드
place

string

기본 장소의 리소스 이름이며 'places/{id}' 형식입니다.
id

string

기본 장소의 장소 ID입니다.
googleMapsLinks

object (GoogleMapsLinks)

다양한 Google 지도 작업을 트리거하는 링크
attribution

object (Attribution)

장소와 함께 표시할 필수 저작자 표시입니다.

통합 필드 _location.

_location는 다음 중 하나여야 합니다.
location

object (LatLng)

이 장소의 위치입니다.

LatLng

JSON 표현 
{
  "latitude": number,
  "longitude": number
}
필드
latitude

number

위도입니다. 범위는 [-90.0, +90.0]입니다.
longitude

number

경도입니다. 범위는 [-180.0, +180.0]입니다.
JSON 표현 
{
  "directionsUrl": string,
  "placeUrl": string,
  "writeAReviewUrl": string,
  "reviewsUrl": string,
  "photosUrl": string
}
필드
directionsUrl

string

장소로 가는 경로를 표시하는 링크입니다. 링크는 도착 위치만 채우고 기본 이동 수단 DRIVE을 사용합니다.
placeUrl

string

이 장소를 표시하는 링크입니다.
writeAReviewUrl

string

Google 지도에서 이 장소에 대한 리뷰를 작성할 수 있는 링크입니다.
reviewsUrl

string

Google 지도에서 이 장소의 리뷰를 표시하는 링크입니다.
photosUrl

string

Google 지도에서 이 장소의 사진을 표시하는 링크입니다.

기여 분석

JSON 표현 
{
  "title": string,
  "url": string
}
필드
title

string

저작자 표시에 표시할 제목입니다.
url

string

저작자 표시를 위해 연결할 URL입니다.

DetourSummary

JSON 표현 
{
  "detourDuration": string,
  "localizedDetourDistance": string
}
필드
detourDuration

string (Duration format)

기본 경로에서 이 장소로 우회하는 데 필요한 추가 이동 시간입니다. 경로가 encoded_polyline로 지정된 경우 이 값은 설정되지 않습니다.

소수점 아래가 최대 9자리까지이고 's'로 끝나는 초 단위 기간입니다. 예를 들면 "3.5s"입니다.
localizedDetourDistance

string

기본 경로에서 이 장소로 우회하는 데 필요한 추가 거리로, 요청 언어로 표시되도록 형식이 지정됩니다(예: '1.2마일' 또는 '1.9km').

기간

JSON 표현 
{
  "seconds": string,
  "nanos": integer
}
필드
seconds

string (int64 format)

기간의 부호 있는 초입니다. -315,576,000,000~+315,576,000,000(포함) 사이여야 합니다. 참고: 이 경계는 60초/분 * 60분/시간 * 24시간/일 * 365.25일/년 * 10,000년으로 계산됩니다.
nanos

integer

기간의 나노초 단위로 부호가 있는 초수입니다. 1초 미만의 기간은 0 seconds 필드와 양수 또는 음수 nanos 필드로 표시됩니다. 1초 이상의 기간의 경우 nanos 필드의 0이 아닌 값은 seconds 필드와 동일한 부호여야 합니다. -999,999,999~+999,999,999(끝값 포함) 사이여야 합니다.

도구 주석

도구 주석은 특정 도구의 기본 위험을 설명하기 위해 MCP 클라이언트에 전송됩니다. 대부분의 클라이언트는 이러한 힌트를 신뢰할 수 없는 것으로 취급하지만, 사용자에게 확인 메시지를 보낼 시점을 결정하는 데 사용할 수 있습니다.

제목 문자열과 함께 다음 불리언 힌트가 정의됩니다.

  • readOnlyHint: true인 경우 도구가 환경을 수정하지 않습니다. 기본값: false.
  • destructiveHint: true이면 도구가 파괴적인 작업을 수행할 수 있습니다. false이면 도구는 추가 작업만 수행할 수 있습니다. 기본값은 true입니다.
  • idempotentHint: true인 경우 동일한 인수로 도구를 반복적으로 호출해도 환경에 추가적인 영향을 미치지 않습니다. 기본값: false.
  • openWorldHint: true인 경우 도구는 외부 항목의 '오픈 월드'와 상호작용할 수 있습니다. false이면 도구는 내부 항목과만 상호작용할 수 있습니다. 예를 들어 웹 검색 도구는 오픈 월드이지만 메모리 도구는 오픈 월드가 아닙니다.

Destructive Hint: ❌ | Idempotent Hint: ❌ | Read Only Hint: ✅ | Open World Hint: ❌