Maps Tools Resolution API

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

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, Маунтин-Вью, Калифорния" или "Эйфелева башня, Париж").
  • Общие запросы по категориям (например, "рестораны в Нью-Йорке") или названия сетей без указания местоположения (например, "Starbucks") не поддерживаются и могут не распознаваться.
• Требования к 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 Картах.

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

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

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

Как интерпретировать ответ

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

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

Ошибки на уровне отдельных объектов

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

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

Отказы верхнего уровня

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

• Недействительный запрос (400 INVALID_ARGUMENT). Запрос содержит более 20 объектов, запрос ResolveNames не содержит запросов или содержит запрос с пустым значением text, или запрос ResolveMapsUrls содержит пустой URL или 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 места и один 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:

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