Поиск на маршруте

Инструмент search_along_route позволяет LLM находить места вдоль маршрута путешествия по запросу на естественном языке, например станции зарядки ЭМ по пути к озеру Тахо или кофейни между Сан-Франциско и Сан-Хосе. Инструмент возвращает созданную ИИ сводку по подходящим местам и компромиссам, на которые придется пойти, чтобы заехать в них. Для каждого места, упомянутого в сводке, ответ также включает идентификатор места, координаты широты и долготы, ссылки на Google Карты, обязательную атрибуцию и показатели объезда.

Каждый запрос search_along_route – это вариант Pro, который оплачивается по коду Maps Grounding Pro.

Вы можете вызвать search_along_route через сервер MCP или как метод REST searchAlongRoute. На этой странице описаны параметры запроса, способы указания маршрута, содержимое ответа и порядок оплаты запросов. Полные схемы приведены в справочнике по MCP search_along_route и справочнике по REST searchAlongRoute.

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

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

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

Option Описание
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, в сводку включается расширенная информация о местах, например статистика из отзывов, позиции в меню, атмосфера, советы посетителей, наличие устройств для зарядки ЭМ или цены на бензин. Значение по умолчанию – false.
language_code Необязательное поле. Код языка по стандарту BCP-47 для сводки и локализованного расстояния объезда, например en-US или ja. Значение по умолчанию – en-US.
region_code Необязательное поле. Двухбуквенный код региона пользователя по стандарту CLDR, например US или CA. Влияет на названия мест в зависимости от региона и может влиять на результаты в соответствии с действующим законодательством.

Укажите маршрут

В каждом запросе search_along_route маршрут должен быть указан с помощью одного из трех взаимоисключающих полей. Если вы укажете больше одного поля или не укажете ни одного, то получите ошибку INVALID_ARGUMENT.

В таблице ниже сравниваются три способа указания маршрута.

Параметры маршрута Формат ввода Поддерживаемые способы передвижения Возвраты: detourDuration Для чего его можно использовать
retrieval_token Строка retrievalToken из предыдущего ответа compute_routes (действительна в течение 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 как retrieval_token в search_along_route.

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

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

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

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

Примеры

В следующем запросе 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
}

В примере ниже используется retrieval_token из предыдущего ответа compute_routes:

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

Замените RETRIEVAL_TOKEN строкой retrievalToken, возвращенной compute_routes.

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

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 – краткое описание результатов поиска и компромиссов при объезде на естественном языке. Может содержать цитаты с отсчетом от нуля, например [0], которые сопоставляются с записями в results.
  • results[] – ранжированный список мест, упомянутых в сводке. Каждая запись содержит:
    • place: подробная информация о месте:
      • place – название ресурса места в формате places/{id}.
      • id – идентификатор места. Его можно использовать с другими API платформы Google Карт, например чтобы показать место на карте.
      • location – координаты широты и долготы места.
      • googleMapsLinks: ссылки на Google Карты для места (placeUrl), маршрутов (directionsUrl), отзывов (reviewsUrl), фотографий (photosUrl) и написания отзыва (writeAReviewUrl).
      • attribution – указание авторства, которое должно отображаться вместе с местом. Подробнее о требованиях к указанию авторства…
    • detourSummary – дополнительное время в пути и расстояние, необходимое для остановки в этом месте на маршруте:
      • localizedDetourDistance – дополнительное расстояние, отформатированное на языке запроса, например "1.2 mi" или "1.9 km".
      • detourDuration – дополнительное время в пути в виде строки, например "180s". Это поле не задано, если маршрут указан с помощью encoded_polyline.
  • contentToken – токен визуализации данных агента (предварительная версия), который позволяет бесплатно показывать места в ответе с помощью Places UI Kit. Возвращается, если ответ содержит хотя бы одно место.

Подробные сведения о полях приведены в справочнике по search_along_route.

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

Каждый запрос search_along_route – это одно оплачиваемое событие в рамках SKU Maps Grounding Pro. Если вы установите для параметра include_extended_details значение true или для параметра routing_preference значение ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL, дополнительная плата взиматься не будет. Если агент сначала вызывает compute_routes, а затем передает retrieval_token в search_along_route, каждый вызов инструмента оплачивается как отдельный запрос.

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

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