MCP Tools Reference: mapstools.googleapis.com

도구: search_places

사용자의 요청이 장소, 비즈니스, 주소, 위치, 관심 장소 또는 기타 Google 지도 관련 검색인 경우 이 도구를 호출합니다.

입력 요구사항 (중요):

  1. text_query (문자열 - 필수): 기본 검색 쿼리입니다. 사용자가 무엇을 찾고 있는지 명확하게 정의해야 합니다.

    • 예: 'restaurants in New York', 'coffee shops near Golden Gate Park', 'SF MoMA', '1600 Amphitheatre Pkwy, Mountain View, CA, USA', 'pets friendly parks in Manhattan, New York', 'date night restaurants in Chicago', 'accessible public libraries in Los Angeles'
    • 특정 장소 세부정보: 요청된 속성 (예: 'Google Store Mountain View opening hours', 'SF MoMa phone number', 'Shoreline Park Mountain View address')을 포함합니다.

  2. location_bias (객체 - 선택사항): 특정 지리적 영역 근처의 결과를 우선순위로 지정하는 데 사용합니다.

    • 형식: {"location_bias": {"circle": {"center": {"latitude": [value], "longitude": [value]}, "radius_meters": [value (optional)]}}}
    • 사용:
      • 5km 반경으로 편향되도록 설정하려면 {"location_bias": {"circle": {"center": {"latitude": 34.052235, "longitude": -118.243683}, "radius_meters": 5000}}}
      • 중심점을 향하도록 강하게 편향시키려면 {"location_bias": {"circle": {"center": {"latitude": 34.052235, "longitude": -118.243683}}}} (radius_meters 생략)

  3. language_code (문자열 - 선택사항): 검색 결과 요약을 표시할 언어입니다.

    • 형식: 두 글자로 된 언어 코드(ISO 639-1)이며, 필요에 따라 밑줄과 두 글자로 된 국가 코드(ISO 3166-1 alpha-2)가 뒤에 올 수 있습니다(예: en, ja, en_US, zh_CN, es_MX). 언어 코드가 제공되지 않으면 결과가 영어로 표시됩니다.

  4. region_code (문자열 - 선택사항): 사용자의 유니코드 CLDR 지역 코드입니다. 이 매개변수는 사용 가능한 경우 지역별 장소 이름과 같은 장소 세부정보를 표시하는 데 사용됩니다. 이 매개변수는 관련 법률에 따라 결과에 영향을 줄 수 있습니다.

    • 형식: 2자리 국가 코드(ISO 3166-1 alpha-2)(예: US, CA)

도구 호출 안내:

  • 위치 정보 (중요): 검색에 충분한 위치 정보가 포함되어야 합니다. 위치가 모호한 경우 (예: '피자 가게'만) text_query에서 지정해야 합니다 (예: '뉴욕의 피자 가게'). 또는 location_bias 매개변수를 사용하세요. 명확성을 위해 필요한 경우 도시, 주/도, 지역/국가 이름을 포함합니다.

  • 항상 최대한 구체적이고 맥락이 풍부한 text_query를 제공하세요.

  • 좌표가 명시적으로 제공되거나 사용자의 알려진 컨텍스트에서 위치를 추론하는 것이 더 나은 결과를 위해 적절하고 필요한 경우에만 location_bias를 사용하세요.

  • 그라운딩된 출력은 가능한 경우 attribution 필드의 정보를 사용하여 소스를 표시해야 합니다.

다음 코드 샘플은 curl를 사용하여 search_places 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_places",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

입력 스키마

SearchText 요청 메시지입니다.

SearchTextRequest

JSON 표현 
{
  "textQuery": string,
  "languageCode": string,
  "regionCode": string,

  // Union field _location_bias can be only one of the following:
  "locationBias": {
    object (LocationBias)
  }
  // End of list of possible types for union field _location_bias.
}
필드
textQuery

string

필수 항목입니다. 텍스트 쿼리입니다.
languageCode

string

선택사항입니다. 요약이 반환되도록 요청할 언어입니다. 언어 코드가 지정되지 않았거나 인식되지 않는 경우 영어를 선호하는 요약이 반환됩니다.

예를 들어 영어의 경우 'en'입니다.

지원되는 언어의 현재 목록: https://developers.google.com/maps/faq#languagesupport
regionCode

string

선택사항입니다. 요청이 전송되는 위치의 유니코드 국가/지역 코드 (CLDR)입니다. 이 매개변수는 사용 가능한 경우 지역별 장소 이름과 같은 장소 세부정보를 표시하는 데 사용됩니다. 이 매개변수는 관련 법규에 따라 결과에 영향을 미칠 수 있습니다.

예를 들어 미국의 경우 'US'입니다.

자세한 내용은 https://www.unicode.org/cldr/charts/latest/supplemental/territory_language_information.html을 참고하세요.

현재 3자리 지역 코드는 지원되지 않습니다.

통합 필드 _location_bias.

_location_bias는 다음 중 하나여야 합니다.
locationBias

object (LocationBias)

검색 결과를 편향시킬 선택적 지역입니다. 명시적 위치가 text_query에 있으면 이 필드 대신 검색 결과에 편향을 주기 위해 사용됩니다.

LocationBias

JSON 표현 
{
  "circle": {
    object (Circle)
  }
}
필드
circle

object (Circle)

선택사항입니다. 중심점과 반지름으로 정의된 원입니다. radius_meters은 선택사항입니다. 설정하지 않으면 결과가 중심점을 향해 편향됩니다.

원

JSON 표현 
{
  "center": {
    object (LatLng)
  },

  // Union field _radius_meters can be only one of the following:
  "radiusMeters": number
  // End of list of possible types for union field _radius_meters.
}
필드
center

object (LatLng)

필수 항목입니다. 원의 중심점입니다.

통합 필드 _radius_meters.

_radius_meters는 다음 중 하나여야 합니다.
radiusMeters

number

원의 반지름(미터)입니다. 반경은 50,000미터 이내여야 합니다.

LatLng

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

number

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

number

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

출력 스키마

SearchText의 응답 메시지입니다.

SearchTextResponse

JSON 표현 
{
  "places": [
    {
      object (PlaceView)
    }
  ],
  "summary": string
}
필드
places[]

object (PlaceView)

출력 전용입니다. 요약에 언급된 장소 목록입니다.
summary

string

출력 전용입니다. 검색 결과의 자연어 요약입니다. 요약에는 '[0]', '[1]', '[2]' 등 0부터 시작하는 인용이 포함될 수 있습니다. 이러한 인용은 places 필드의 해당 위치에 매핑됩니다.

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입니다.

도구 주석

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

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

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

파괴적 힌트: ❌ | 동일한 힌트: ❌ | 읽기 전용 힌트: ✅ | 오픈 월드 힌트: ❌