Поиск мест

Инструмент search_places позволяет LLM находить места на Google Картах по запросу на естественном языке. Инструмент возвращает созданную ИИ сводку по подходящим местам. Для каждого места, упомянутого в сводке, также возвращаются идентификатор места, географические координаты, ссылки на Google Карты и атрибуция.

Вы можете вызвать search_places через сервер MCP или как метод REST searchText. На этой странице описаны параметры запроса, в том числе параметры Pro, содержимое ответа и порядок оплаты запросов. Полные схемы приведены в справочнике по MCP search_places и справочнике по REST searchText.

Параметры запроса

LLM задает эти параметры при вызове инструмента на основе запроса пользователя и описания инструмента. Вы можете повлиять на то, какие варианты использует модель, с помощью собственных инструкций. Подробнее о том, как управлять использованием Pro…

В таблице ниже описаны параметры запроса для search_places.

Возможности Pro

Два варианта выбора Maps Grounding Pro SKU. Запрос, в котором используется одна или обе функции, оплачивается по коду Pro:

Запросы, в которых не используется ни один из вариантов, включая запросы с параметром page_size от 1 до 5, оплачиваются по коду Essentials.

Расширенная информация о месте

Задайте для параметра include_extended_details значение true, если в запросе пользователя нужны качественные данные, условия в реальном времени или специализированные атрибуты, например:

• Что говорят пользователи: отзывы, настроения клиентов и обратная связь.
• Особые предложения: позиции меню, блюда, фирменные блюда, напитки или особенности бизнеса.
• Атмосфера: декор, эстетика, обстановка или настроение.
• Полезные советы для посетителей: нужно ли бронировать заранее, правила для посетителей без бронирования, время ожидания, загруженность, парковка и удобства.
• Близость: расстояние или время в пути от местоположения, указанного в запросе, или от центра location_bias, когда пользователь спрашивает, что находится поблизости или ближе всего.

Содержание сводки зависит от запроса и данных, доступных для каждого места. В ответах могут быть представлены не все типы статистики.

Оставьте значение по умолчанию (false) для стандартных поисковых запросов: кухни или типы магазинов, адреса, контактная информация, часы работы и стандартные удобства. Запросы с расширенными сведениями обрабатываются дольше.

Расширенные сведения не меняют структуру ответа. Если их нет, в описании каждого места будет одно-два предложения. Благодаря им у каждого места появляется более подробное описание, основанное на данных Google Карт, в том числе на отзывах. Структурированные записи places одинаковы для обоих кодов SKU.

Пример

В следующем запросе MCP запрашивается до 8 мест с расширенными сведениями. Оплата за нее взимается по тарифу Pro:

{
  "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
}

В примере ниже показано, как отправить такой же запрос в метод REST searchText.

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-d '{
  "textQuery": "date night Italian restaurants in Chicago",
  "pageSize": 8,
  "includeExtendedDetails": true
}' \
"https://mapstools.googleapis.com/v1:searchText"

Укажите вместо API_KEY свой ключ API.

Без расширенных сведений сводка описывает каждое место в одном или двух предложениях:

Пример траттории [0] (4,6★ (1250) · 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 – краткое описание результатов поиска на естественном языке. Может содержать цитаты с нумерацией от нуля, например [0], которые сопоставляются с записями в places.
• places[] – места, упомянутые в сводке. Для каждого места указывается:
  • place – название ресурса места в формате places/{id}.
  • id – идентификатор места. Его можно использовать с другими API платформы Google Карт, например чтобы показать место на карте.
  • location – координаты широты и долготы места.
  • googleMapsLinks: ссылки на Google Карты для места (placeUrl), маршрутов (directionsUrl), отзывов (reviewsUrl), фотографий (photosUrl) и написания отзыва (writeAReviewUrl).
  • attribution – указание авторства, которое должно отображаться вместе с местом. Подробнее о требованиях к указанию авторства…
• contentToken – токен визуализации данных агента (предварительная версия), который позволяет бесплатно показывать места в ответе с помощью Places UI Kit. Возвращается, если ответ содержит хотя бы одно место.

Ответ имеет одинаковую структуру для обоих SKU, а также для MCP и REST. Подробные сведения о полях приведены в справочнике по search_places.

Оплата и квоты

Каждый запрос search_places – это одно оплачиваемое событие:

• Запрос, в котором не используются функции Pro, оплачивается по коду Maps Grounding Essentials SKU.
• Запрос, в котором используется вариант Pro, оплачивается по коду Maps Grounding Pro SKU. Если вы используете оба варианта в одном запросе, плата не изменится. Цены на Pro приведены в статье Сравнение Essentials, Pro и обоснования с Google Картами.

Если вы показываете места из ответа search_places с помощью Places UI Kit, то можете использовать токен визуализации данных агента (предварительная версия), чтобы за запросы Places UI Kit не взималась плата.

Квота search_places составляет 300 запросов в минуту на проект и является общей для обоих кодов SKU. Цены приведены в основной таблице цен и таблице цен для Индии.