지역 정보 검색

search_places 도구를 사용하면 LLM이 자연어 쿼리에서 Google 지도의 장소를 찾을 수 있습니다. 도구는 일치하는 장소에 대한 AI 생성 요약을 반환합니다. 요약에서 인용하는 각 장소에 대해 장소 ID, 좌표, Google 지도 링크, 저작자 표시도 반환합니다.

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

요청 옵션

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

옵션	설명
`text_query`	필수 항목입니다. 검색어입니다(예: `coffee shops near Golden Gate Park`). 쿼리에 명확한 위치 정보가 충분히 포함되어 있거나 요청에 `location_bias`가 포함되어야 합니다.
`location_bias`	결과를 편향시킬 원 (`center` 및 선택사항인 `radius_meters`, 최대 50,000미터)입니다. `text_query`에서 명시적 위치를 지정하면 해당 위치가 대신 사용됩니다.
`language_code`	요약의 언어입니다(예: `en` 또는 `ja`). 기본값은 영어입니다.
`region_code`	사용자의 CLDR 지역 코드입니다(예: `US`). 지역별 장소 이름에 영향을 미치며 관련 법규에 따라 결과에 영향을 미칠 수 있습니다.
`page_size`	반환할 최대 장소 수입니다. 기본값은 5입니다. 6~10의 값은 Pro 옵션입니다. 10을 초과하는 값은 `INVALID_ARGUMENT` 오류를 반환합니다. 서비스에서 요청한 것보다 적은 수의 장소를 반환할 수 있습니다.
`include_extended_details`	`true`인 경우 요약에 확장된 장소 세부정보가 포함됩니다. 이는 Pro 옵션입니다. 기본값은 `false`입니다.

Pro 옵션

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

Pro 옵션	사용 시기
`include_extended_details`을 `true`으로 설정	사용자의 요청에 리뷰의 요약 정보, 메뉴 하이라이트, 분위기, 방문자 팁과 같은 확장된 장소 세부정보가 필요합니다.
`page_size`(6~10세)	사용자가 5개 이상의 장소를 비교하려고 합니다.

page_size가 1~5인 요청을 포함하여 두 옵션을 모두 사용하지 않는 요청은 Essentials SKU로 청구됩니다.

확장된 장소 세부정보

사용자의 요청에 다음과 같은 정성적 인사이트, 실시간 조건 또는 전문 속성이 필요한 경우 include_extended_details를 true로 설정합니다.

리뷰 작성자의 의견: 리뷰 기반 통계, 고객 반응, 의견
구체적인 제품: 메뉴 항목, 요리, 특산품, 음료 또는 비즈니스 하이라이트
분위기: 인테리어, 미적 요소, 분위기 또는 기분
실용적인 방문자 팁: 사전 예약 필요 여부, 예약 없이 방문 시 정책, 대기 시간, 장소의 혼잡도, 주차, 시설
근접성: 사용자가 근처에 있거나 가장 가까운 항목을 물을 때 검색어 위치 또는 location_bias 중심으로부터의 거리 또는 이동 시간입니다.

요약의 인사이트는 쿼리와 각 장소에 사용할 수 있는 데이터에 따라 달라집니다. 모든 응답에 모든 유형의 통계가 표시되는 것은 아닙니다.

요리 또는 매장 유형, 주소, 연락처 정보, 영업시간, 표준 편의시설과 같은 일반 검색의 경우 false (기본값)로 둡니다. 세부정보가 확장된 요청은 완료하는 데 시간이 더 오래 걸립니다.

확장된 세부정보는 응답 구조를 변경하지 않습니다. 이러한 매개변수가 없으면 요약은 각 장소를 한두 문장으로 설명합니다. 이를 통해 각 장소는 리뷰의 통계를 비롯한 더 많은 Google 지도 데이터를 활용하는 더 긴 설명을 얻을 수 있습니다. 구조화된 places 항목은 두 SKU 모두 동일합니다.

예

다음 요청은 확장된 세부정보가 있는 장소를 최대 8개 요청합니다. Pro SKU로 청구됩니다.

{
  "method": "tools/call",
  "params": {
    "name": "search_places",
    "arguments": {
      "text_query": "date night Italian restaurants in Chicago",
      "page_size": 8,
      "include_extended_details": true
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}

확장된 세부정보가 없으면 요약은 각 장소를 한두 문장으로 설명합니다.

Example Trattoria [0] (4.6★ (1,250) · 123 W Example St · $$$) A neighborhood trattoria known for handmade pasta and a long wine list.

With extended details, the summary adds what reviewers highlight and practical tips:

Example Trattoria [0] (4.6★ (1,250) · 123 W Example St · $$$) 촛불이 켜진 친밀한 분위기의 식당으로, 리뷰어들은 로맨틱하지만 주말에는 시끄럽다고 설명합니다. 대표적인 요리로는 탈리아텔레 알 라구, 부라타, 티라미수가 있습니다. 예약하는 것이 좋습니다. 예약 없이 방문하는 경우 금요일과 토요일 저녁에는 30~45분 정도 기다려야 할 수 있으며 노상 주차 공간이 제한되어 있습니다.

응답

응답에는 다음이 포함됩니다.

summary: 검색 결과의 자연어 요약입니다. places의 항목에 매핑되는 0 기반 인용(예: [0])이 포함될 수 있습니다.
places[]: 요약에 언급된 장소입니다. 각 장소에는 다음이 포함됩니다.
- place: 장소의 리소스 이름(places/{id} 형식)
- id: 장소 ID입니다. 다른 Google Maps Platform API와 함께 사용하여 지도에 장소를 표시할 수 있습니다.
- location: 장소의 위도 및 경도입니다.
- googleMapsLinks: 장소 (placeUrl), 경로 (directionsUrl), 리뷰 (reviewsUrl), 사진(photosUrl), 리뷰 작성 (writeAReviewUrl)에 대한 Google 지도 링크입니다.
- attribution: 장소와 함께 표시해야 하는 저작자 표시입니다. 저작자 표시 요구사항을 참고하세요.

응답은 두 SKU 모두 동일한 구조를 갖습니다. 필드 세부정보는 search_places 참조를 확인하세요.

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

제한된 정식 버전 기간에는 Pro 허용 목록에 있는 프로젝트에서만 Pro 옵션을 사용할 수 있습니다. 프로젝트가 아직 허용 목록에 없으면 Pro 옵션은 거부되지 않고 무시됩니다.

include_extended_details는 false로 취급됩니다.
10을 초과하는 값을 포함하여 5를 초과하는 page_size 값은 5로 줄어듭니다.

요청은 Essentials SKU로 청구됩니다. 액세스를 요청하려면 제한된 정식 버전 중 Pro 옵션을 참조하세요.

결제 및 할당량

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

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

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