Maps Tools Resolution API

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

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

Подготовка

Чтобы использовать 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 долл. США) по коду Places API Text Search 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 map: ответ содержит карту failedRequests.
   • Ключ – это индекс элемента, в котором произошла ошибка, начиная с нуля (в JSON представлен в виде строки).
   • Значение – это объект google.rpc.Status, содержащий код ошибки и сообщение с объяснением, почему не удалось обработать элемент.
4. saveToMapsUrl covers only successes (covers only successes) – ссылка saveToMapsUrl включает только объекты, которые были успешно обработаны. Объекты, которые не удалось перенести, не учитываются.

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

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

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

Повторите попытку только для объектов, которые не удалось перенести из-за ошибки 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:

• Сообщить об ошибке
• Как отправить запрос на добавление функции
• Отправить отзыв