Чтобы переводить контент на ваш предпочитаемый язык, Google использует технологии на основе искусственного интеллекта. Переводы от ИИ могут содержать ошибки.

Maps Tools Resolution API

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

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

Возможности	Метод 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 долл. США) по коду 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. Возвращенный список results (для ResolveNames) или entities (для ResolveMapsUrls) соответствует входному списку 1:1 по индексу.
Пустые элементы для ошибок. Если элемент с индексом i не удалось разрешить, список результатов содержит пустой объект {} с индексом i.
failedRequests map: ответ содержит карту failedRequests.
- Ключ – это индекс элемента, в котором произошла ошибка, начиная с нуля (в JSON представлен в виде строки).
- Значение – это объект google.rpc.Status, содержащий код ошибки и сообщение с объяснением, почему не удалось обработать элемент.
saveToMapsUrl covers only successes (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:

Maps Tools Resolution API Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

Подготовка

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

Ключ API

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

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

Цены

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

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

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

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

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

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

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

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

ResolveNames

Метод: POST

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

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

Ответ JSON

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

Ответ JSON

ResolveMapsUrls

Метод: POST

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

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

Ответ JSON

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

Ответ JSON

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

Ответ JSON

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

Maps Tools Resolution API