Maps Tools Resolution API

Maps Tools Resolution API – это часть Maps Grounding Lite. Он предоставляет конечные точки пакетов, которые преобразуют названия мест и URL Google Карт в идентификаторы мест Google Карт. Полученные идентификаторы мест можно использовать с другими API платформы Google Карт. Каждый ответ также содержит ссылку, которая сохраняет найденные места в виде списка в Google Картах.

Resolution API доступен как в виде методов REST, так и в виде инструментов на сервере Maps Grounding Lite MCP:

Возможности Метод REST Инструмент MCP
Сопоставление названий или адресов местоположений с местами resolveNames resolve_names
Как преобразовать URL Google Карт в места resolveMapsUrls resolve_maps_urls

Подготовка

Чтобы использовать Resolution API, вам нужен облачный проект Google Cloud с включенными платежными функциями и сервисом Maps Grounding Lite API. Инструкции приведены в статье Как включить сервис Maps Grounding Lite в проекте Google Cloud.

Доступ к API и аутентификация

Resolution API поддерживает как ключ API, так и учетные данные OAuth 2.0.

Ключ API

Вы можете аутентифицировать запросы, передав действительный ключ API платформы Google Карт в заголовке X-Goog-Api-Key или добавив его к URL запроса:

https://mapstools.googleapis.com/v1:resolveNames?key=API_KEY

В примерах на этой странице замените API_KEY своим ключом API.

Области действия OAuth 2.0

Если вы используете авторизацию OAuth, поддерживается следующая область действия:

  • https://www.googleapis.com/auth/maps-platform.mapstools

Лимиты на использование

Для Resolution API по умолчанию действуют следующие квоты:

  • ResolveNames: 600 запросов в минуту на проект.
  • ResolveMapsUrls: 600 запросов в минуту на проект.
  • Размер пакета: до 20 запросов или URL на запрос.

Каждый запрос считается за один, независимо от того, сколько элементов он содержит.

Цены

Запросы к ResolveNames и ResolveMapsUrls оплачиваются бесплатно (0 долл. США) по SKU Places API текстовый поиск Essentials (IDs Only). Как и для других функций Maps Grounding Lite, в вашем проекте должен быть платежный аккаунт.

Проверка запросов и ограничения

Чтобы предотвратить чрезмерную нагрузку и обеспечить быстрое время отклика, пакетные запросы строго проверяются:

  • Ограничение на размер пакета. Оба метода позволяют добавлять не более 20 элементов в запрос.
  • Требования к ResolveNames:
    • Для каждого объекта в queries должен быть указан непустой параметр text.
    • Запросы должны содержать название или адрес определенного места, например "Googleplex, Маунтин-Вью, Калифорния" или "Эйфелева башня, Париж".
    • Общие запросы по категориям (например, "рестораны в Москве") или названия сетей без указания местоположения (например, "Шоколадница") не поддерживаются и могут не обрабатываться.
  • Требования к ResolveMapsUrls:
    • Каждый URL должен быть действительным URL Google Карт.
    • Поддерживаются следующие форматы:
      • Стандартный URL места: https://www.google.com/maps/place/...
      • Сокращенный URL: https://maps.app.goo.gl/...
    • Общие URL Карт, основанные на запросах (например, https://maps.google.com/?q=restaurant), и URL, которые не указывают на одно уникальное место, не поддерживаются.

Сохраняйте распознанные места в Google Картах

Если хотя бы один элемент в пакете разрешен, ответ включает поле saveToMapsUrl. Это одна ссылка на Google Карты, которая содержит все успешно сопоставленные места в пакете. Предоставьте эту ссылку пользователям, которые хотят сохранить, отправить или открыть найденные места в виде списка в Google Картах.

Всегда используйте ссылку, возвращенную API. Не создавайте ссылку самостоятельно. Если ни один элемент в пакете не сопоставлен, ответ не будет содержать saveToMapsUrl.

Как обрабатывать частичные ошибки

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

Интерпретация ответа

  1. Гарантированное соответствие 1:1. Возвращенный список results (для ResolveNames) или entities (для ResolveMapsUrls) сопоставляется со входным списком 1:1 по индексу.
  2. Пустые элементы для ошибок. Если элемент с индексом i не удалось разрешить, список результатов содержит пустой объект {} с индексом i.
  3. Карта failedRequests. Ответ содержит карту failedRequests.
    • Ключ – это индекс элемента, с которым возникла проблема, начиная с нуля (в JSON представлен в виде строки).
    • Значение – это объект google.rpc.Status, содержащий код ошибки и сообщение с объяснением, почему не удалось обработать элемент.
  4. saveToMapsUrl covers only successes (содержит только успешные результаты). Ссылка saveToMapsUrl содержит только объекты, которые были успешно обработаны. Объекты, которые не удалось перенести, не учитываются.

Не думайте, что весь пакет не был обработан из-за ошибки в одном элементе. Всегда проверяйте failedRequests, чтобы узнать, какие объекты не удалось сопоставить.

Ошибки на уровне объектов

В таблице ниже перечислены ошибки, которые могут возникнуть при обработке отдельных объектов в failedRequests.

Метод Причина Код Сообщение
ResolveNames Не удалось найти место по указанному названию или адресу. 5 (NOT_FOUND) Place not found.
ResolveMapsUrls URL не соответствует месту. 3 (INVALID_ARGUMENT) Failed to resolve Maps URL to a place.
Оба способа При разрешении объекта произошла внутренняя ошибка. 13 (INTERNAL) Internal server error. Please retry. If the problem persists, please open a support case. https://goo.gle/maps-platform-support

Повторите попытку только для объектов, которые не удалось перенести из-за ошибки INTERNAL.

Ошибки верхнего уровня

API возвращает ошибку верхнего уровня вместо частичного ответа в следующих случаях:

  • Недопустимый запрос (400 INVALID_ARGUMENT). Запрос содержит более 20 элементов, запрос ResolveNames не содержит запросов или содержит запрос с пустым значением text, или запрос ResolveMapsUrls содержит URL, который является пустым или синтаксически недействительным. Если хотя бы один элемент недействителен, запрос не будет выполнен.
  • Ошибки аутентификации, разрешений или квот. Например, ключ API отсутствует или недействителен, или запрос превышает лимиты на использование.
  • Ошибки сервера (500 INTERNAL): повторите запрос.

Как использовать Resolution API с MCP

Сервер MCP Maps Grounding Lite по адресу https://mapstools.googleapis.com/mcp предоставляет Resolution API в виде двух инструментов:

  • resolve_names – сопоставляет набор названий или адресов мест с идентификаторами мест.
  • resolve_maps_urls – преобразует пакет URL Google Карт в идентификаторы мест.

Когда вы настроите LLM для использования сервера MCP Maps Grounding Lite, эти инструменты станут доступны наряду с другими инструментами Maps Grounding Lite. Инструменты принимают те же входные данные, применяют те же ограничения и возвращают тот же ответ о частичном сбое, что и методы REST.

Ответы инструмента содержат поле save_to_maps_url. В описаниях инструментов LLM дается инструкция показывать эту ссылку, когда пользователь хочет сохранить, поделиться или открыть найденные места в виде списка в Google Картах, вместо того чтобы создавать ссылку самостоятельно.

В следующем примере используется curl для прямого вызова инструмента resolve_names:

curl --location 'https://mapstools.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--header 'X-Goog-Api-Key: API_KEY' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "resolve_names",
    "arguments": {
      "queries": [
        { "text": "Googleplex, Mountain View, CA" },
        { "text": "Eiffel Tower, Paris" }
      ]
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Чтобы вызвать resolve_maps_urls, задайте для name значение resolve_maps_urls и передайте массив urls в arguments.

Спецификация REST API и примеры curl

ResolveNames

Метод: POST

https://mapstools.googleapis.com/v1:resolveNames

Формат тела запроса

{
  "queries": [
    { "text": "string" }
  ],
  "locationBias": {
    "viewport": {
      "low": { "latitude": number, "longitude": number },
      "high": { "latitude": number, "longitude": number }
    }
  },
  "regionCode": "string"
}
  • queries (обязательный): повторяющийся список запросов, которые нужно обработать (не более 20).
  • locationBias (необязательный параметр) – граничная рамка области просмотра, позволяющая сместить результаты в сторону местного региона.
  • regionCode (необязательный) – код страны по CLDR (например, "US" или "FR"), используемый для уточнения результатов.

Пример Curl: успешное разрешение

Этот запрос разрешает "Googleplex" и "Эйфелева башня".

curl -X POST \
-H "Content-Type: application/json" \
-d '{
  "queries": [
    { "text": "Googleplex, Mountain View, CA" },
    { "text": "Eiffel Tower, Paris" }
  ]
}' \
"https://mapstools.googleapis.com/v1:resolveNames?key=API_KEY"
Ответ JSON
{
  "results": [
    {
      "entity": {
        "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
      },
      "confidence": "HIGH"
    },
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ],
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJj61dQgK6j4AR4GeTYWZsKWw,ChIJLU7jZClu5kcR4PcOOO6p3I0"
}

Пример Curl: смешанные результаты (частичный сбой)

В этом примере первый элемент – это текст, который не удается распознать, а второй – действительное место.

curl -X POST \
-H "Content-Type: application/json" \
-d '{
  "queries": [
    { "text": "This is not a real place name at all 123456789" },
    { "text": "Eiffel Tower, Paris" }
  ]
}' \
"https://mapstools.googleapis.com/v1:resolveNames?key=API_KEY"
Ответ JSON
{
  "results": [
    {},
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ],
  "failedRequests": {
    "0": {
      "code": 5,
      "message": "Place not found."
    }
  },
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJLU7jZClu5kcR4PcOOO6p3I0"
}

ResolveMapsUrls

Метод: POST

https://mapstools.googleapis.com/v1:resolveMapsUrls

Формат тела запроса

{
  "urls": [
    "string"
  ]
}
  • urls (обязательный) – повторяющийся список строк URL Google Карт, которые нужно разрешить (не более 20).

Пример Curl: успешное разрешение

В следующем примере разрешается стандартный URL места на Google Картах:

curl -X POST \
-H "Content-Type: application/json" \
-d '{
"urls": [
"https://www.google.com/maps/place/Googleplex/@37.4220041,-122.0862515,17z/data=!3m1!4b1!4m6!3m5!1s0x808fba02425dad8f:0x6c296c66619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6"
]
}' \
"https://mapstools.googleapis.com/v1:resolveMapsUrls?key=API_KEY"
Ответ JSON
{
  "entities": [
    {
      "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
    }
  ],
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJj61dQgK6j4AR4GeTYWZsKWw"
}

Пример Curl: смешанные результаты (частичный сбой)

В следующем примере один URL места действителен, а другой – нет.

curl -X POST \
-H "Content-Type: application/json" \
-d '{
  "urls": [
    "https://www.google.com/maps/place/Googleplex/@37.4220041,-122.0862515,17z/data=!3m1!4b1!4m6!3m5!1s0x808fba02425dad8f:0x6c296c66619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6",
    "https://www.google.com/not-a-place"
  ]
}' \
"https://mapstools.googleapis.com/v1:resolveMapsUrls?key=API_KEY"
Ответ JSON
{
  "entities": [
    {
      "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
    },
    {}
  ],
  "failedRequests": {
    "1": {
      "code": 3,
      "message": "Failed to resolve Maps URL to a place."
    }
  },
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJj61dQgK6j4AR4GeTYWZsKWw"
}

Пример Curl: ошибка проверки

В следующем примере в одном запросе передается более 20 URL:

python3 -c 'import json; print(json.dumps({"urls": ["https://www.google.com/maps/place/Googleplex"] * 21}))' | \
curl -X POST \
-H "Content-Type: application/json" \
-d @- \
"https://mapstools.googleapis.com/v1:resolveMapsUrls?key=API_KEY"
Ответ JSON
{
  "error": {
    "code": 400,
    "message": "Request contains more than 20 URLs.",
    "status": "INVALID_ARGUMENT"
  }
}

Отправить отзыв

Чтобы сообщить о проблеме или поделиться отзывом о Resolution API, используйте компонент общедоступной системы отслеживания ошибок Maps Grounding Lite: