Эта страница переведена с помощью Cloud Translation API.

API разрешения инструментов карт (экспериментальная версия)

API разрешения имен в инструментах работы с картами предоставляет конечные точки для пакетной обработки, позволяющие сопоставлять названия местоположений и URL-адреса с идентификаторами мест Google Maps.

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

Экспериментальная версия: API ResolveNames и ResolveMapsUrls находятся на экспериментальной (предварительной) стадии. Продукты и функции предварительной версии могут иметь ограниченную поддержку, а изменения в продуктах и функциях предварительной версии могут быть несовместимы с другими предварительными версиями. На предложения предварительной версии распространяются Условия использования сервиса Google Maps Platform . Для получения дополнительной информации см. описания этапов запуска . Использование ResolveNames и ResolveMapsUrls в экспериментальной версии бесплатно.

Методы аутентификации

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

1. Ключ API

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

https://mapstools.googleapis.com/v1alpha:resolveNames?key=YOUR_API_KEY

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

При использовании авторизации OAuth поддерживаются следующие области действия (scopes):

https://www.googleapis.com/auth/maps-platform.mapstools (Рекомендуется)

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

Для предотвращения чрезмерной нагрузки и обеспечения быстрого отклика пакетные запросы проходят строгую проверку:

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

Обработка частичных ошибок

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

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

Гарантированное соответствие 1:1 : возвращаемые списки результатов (для ResolveNames ) или сущностей (для ResolveMapsUrls ) соответствуют входному списку в соотношении 1:1 .
Пустые элементы при неудачных попытках : Если элемент с индексом i не был разрешен, результирующий список будет содержать пустой объект {} с индексом i .
Карта failedRequests : Ответ содержит карту failedRequests .
- Ключевым моментом является индекс неудачно обработанного элемента, начинающийся с 0 (в формате JSON он представлен в виде строки).
- Значение представляет собой объект google.rpc.Status , содержащий конкретный код ошибки (из стандартных статусов gRPC/HTTP) и подробное сообщение, объясняющее причину сбоя.

Сбои верхнего уровня

Ошибка HTTP верхнего уровня (например, 400 Bad Request ) возвращается только в том случае, если запрос не проходит проверку (например, при передаче более 20 элементов или отсутствии обязательных полей).

Спецификация API и примеры использования Curl.

1. API ResolveNames

Метод: ПОСТ

https://mapstools.googleapis.com/v1alpha: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/v1alpha:resolveNames?key=KEY"

JSON-ответ

{
  "results": [
    {
      "entity": {
        "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
      },
      "confidence": "HIGH"
    },
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ]
}

Пример завивки: неоднозначные результаты (частичный провал)

В этом примере первый элемент представляет собой неразрешимый бессмысленный текст, а второй элемент — допустимое местоположение.

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/v1alpha:resolveNames?key=KEY"

JSON-ответ

{
  "results": [
    {},
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ],
  "failedRequests": {
    "0": {
      "code": 5,
      "message": "Place not found."
    }
  }
}

2. API ResolveMapsUrls

Метод: ПОСТ

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

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

{
  "urls": [
    "string"
  ]
}

urls (Обязательно): Повторяющийся список строк URL-адресов Google Maps для разрешения (максимум 20).

Пример использования Curl: Успешное разрешение

Решение проблемы с обработкой стандартной ссылки на место в Google Maps.

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!1s0x808fba024255ad8f:0x6ca26666619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6"
]
}' \
"https://mapstools.googleapis.com/v1alpha:resolveMapsUrls?key=KEY"

JSON-ответ

{
  "entities": [
    {
      "place": "places/ChIJj61VQgK6j4AR4GeTYWZmomw"
    }
  ]
}

Пример завивки: неоднозначные результаты (частичный провал)

Обнаружена одна допустимая ссылка на сайт и одна некорректная/неподдерживаемая ссылка.

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!1s0x808fba024255ad8f:0x6ca26666619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6",
    "https://www.google.com/not-a-place"
  ]
}' \
"https://mapstools.googleapis.com/v1alpha:resolveMapsUrls?key=KEY"

JSON-ответ

{
  "entities": [
    {
      "place": "places/ChIJj61VQgK6j4AR4GeTYWZmomw"
    },
    {}
  ],
  "failedRequests": {
    "1": {
      "code": 3,
      "message": "Invalid URL."
    }
  }
}

Пример использования 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/v1alpha:resolveMapsUrls?key=KEY"

JSON-ответ

{
  "error": {
    "code": 400,
    "message": "Request contains more than 20 URLs.",
    "status": "INVALID_ARGUMENT"
  }
}