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 (строка). Значение retrieval_token, возвращенное предыдущим вызовом compute_routes для маршрута DRIVE. Используйте этот вариант, если маршрут уже рассчитан. Токен действителен в течение 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 (логическое значение, необязательно). Установите значение true, только если в запросе требуются качественные отзывы, конкретные пункты меню или предложения, атмосфера, советы посетителей или загруженность, наличие устройства для зарядки ЭМ, цены на бензин или другие подробные качественные данные. Значение по умолчанию – false. Если включить эту функцию, задержка может увеличиться.

  6. language_code (строка, необязательно). Язык сводки результатов и информации о местах, например en, ja, en-US. Значение по умолчанию – en-US.

  7. region_code (строка, необязательно). Код региона пользователя в формате Unicode CLDR, например US, CA.

Инструкции по вызову инструмента

  • Каждый результат включает объект detour_summary (если доступен), описывающий дополнительное расстояние (localized_detour_distance) и, если маршрут не был задан как encoded_polyline, дополнительное время (detour_duration), необходимое для остановки в этом месте. Используйте его, чтобы сравнивать варианты.
  • Ответ summary может содержать цитаты, начинающиеся с нуля (например, "[0]"), которые ссылаются на записи в results.
  • Обоснованные выходные данные должны быть соотнесены с источником с помощью поля attribution каждого results[].place, если оно доступно.

В примере кода ниже показано, как использовать curl для вызова инструмента MCP search_along_route.

Запрос 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

Обязательно. Поисковый запрос на естественном языке, например "зарядные станции для электромобилей" или "кофе".
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)

Обязательно. Пункт отправления (адрес, идентификатор места или географические координаты).
destination

object (Waypoint)

Обязательно. Пункт назначения (адрес, идентификатор места или географические координаты).

Путевая точка

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

Идентификатор места, связанный с путевой точкой.
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

Только для вывода. Сводка результатов поиска и компромиссов при объезде на естественном языке. Может содержать ссылки, начинающиеся с нуля (например, "[0]", "[1]"), которые указывают на соответствующие записи в списке results.
contentToken

string

Только для вывода. Зашифрованный токен, который содержит контекст поиска и может быть передан в сервисы визуальной отрисовки Google Карт, SDK или агентный набор инструментов интерфейса Карт (A2UI) для показа интерактивных компонентов интерфейса в результатах поиска.

Результат

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

Идентификатор места, к которому относится адрес.
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.

Продолжительность в секундах, может содержать до девяти дробных цифр и заканчиваться на букву s. Пример: "3.5s".
localizedDetourDistance

string

Дополнительное расстояние, которое нужно проехать, чтобы добраться до этого места с основного маршрута. Форматируется для отображения на языке запроса (например, "1,2 мили" или "1,9 км").

Продолжительность

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

Доли секунды со знаком и наносекундным разрешением. Продолжительность менее одной секунды представлена полем seconds со значением 0 и полем nanos с положительным или отрицательным значением. Если продолжительность составляет одну секунду или больше, ненулевое значение в поле nanos должно иметь тот же знак, что и в поле 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: ❌