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

Рекомендации по использованию Street View Static API

Статические веб-API платформы Google Карт – это набор HTTP-интерфейсов, которые позволяют создавать изображения для встраивания непосредственно на веб-страницы.

Веб-сервисы платформы Google Карт – это набор HTTP-интерфейсов, которые предоставляют географические данные для ваших приложений карт.

В этом руководстве описаны некоторые распространенные методы, которые помогут вам настроить запросы к сервису изображений и веб-сервису, а также обрабатывать ответы сервиса. Дополнительную информацию о Street View Static API можно найти в руководстве для разработчиков.

API статических изображений Просмотра улиц работает как статический веб-API, а сервис метаданных – как веб-сервис. Подробнее о метаданных изображений Просмотра улиц…

Что такое Static Web API?

Статические веб-API платформы Google Карт позволяют встраивать изображения Google Карт в веб-страницы без использования JavaScript или динамической загрузки страниц. Статические веб-API создают изображения на основе параметров URL, которые отправляются с помощью стандартного запроса HTTPS.

Типичный запрос к Street View Static API имеет следующий вид:

  https://www.googleapis.com/streetview/z/x/y?parameters

Что такое веб-сервис?

Веб-сервисы платформы Google Карт – это интерфейс для запроса данных API Карт из внешних сервисов и использования этих данных в приложениях Карт. Эти сервисы предназначены для использования вместе с картой в соответствии с Лицензионными ограничениями Условий использования платформы Google Карт.

Веб-сервисы Maps API используют HTTP- или HTTPS-запросы к определенным URL, передавая параметры URL или данные POST в формате JSON в качестве аргументов сервисам. Как правило, эти сервисы возвращают данные в теле ответа в формате JSON, который можно проанализировать или обработать в приложении.

Запрос метаданных Street View Static API имеет следующий вид:

https://maps.googleapis.com/maps/api/streetview/parameters

Доступ к SSL и TLS

Протокол HTTPS является обязательным для всех запросов к платформе Google Карт, в которых используются ключи API или содержатся пользовательские данные. Запросы, отправленные по протоколу HTTP и содержащие данные деликатного характера, могут быть отклонены.

Создание действительного URL

URL, введенный в адресную строку браузера, не всегда бывает действительным. Он может содержать специальные символы (например, "上海+中國"). Перед тем как выполнить переход по указанному адресу, браузер должен преобразовать эти символы в другую кодировку. Аналогичным образом любой код, который создает или получает данные в формате UTF-8, может считать URL-адреса с символами UTF-8 действительными, но ему потребуется преобразовать эти символы, прежде чем отправлять их на веб-сервер. Этот процесс называется кодированием URL или процентным кодированием.

Специальные символы

Необходимость преобразования символов связана с тем, что все URL должны соответствовать синтаксису, указанному в спецификации унифицированного идентификатора ресурсов (URI). На практике это значит, что URL должны содержать только определенный набор символов ASCII: стандартные буквенно-числовые символы и несколько зарезервированных символов, используемых в URL в качестве управляющих.

Символы, которые можно использовать в URL

Тип	Символы	Использование в URL-адресе
Буквенно-числовые	a b c d e f g h i j k l m n o p q r s t u v w x y z A B C D E F G H I J K L M N O P Q R S T U V W X Y Z 0 1 2 3 4 5 6 7 8 9	Текстовые строки, схема (`http`), порт (`8080`) и т. д.
Незарезервированные	- _ . ~	Текстовые строки
Зарезервированные	! * ' ( ) ; : @ & = + $ , / ? % # [ ]	Управляющие символы или текстовые строки

При создании действительного URL-адреса необходимо использовать только символы из таблицы. Обычно это приводит к пропускам или заменам:

Если символы, которые вы хотите использовать, отсутствуют в указанном выше наборе. Например, символы на иностранных языках, такие как 上海+中國, нужно преобразовать с помощью символов из таблицы. По общепринятому соглашению пробелы (которые запрещены в URL) часто передаются с помощью знака плюса '+'.
Если зарезервированные символы нужно использовать в их первоначальном значении. Например, символ ? используется в URL-адресах для обозначения начала строки запроса. Если вы хотите передать строку "? and the Mysterions", вам необходимо закодировать вопросительный знак ('?').

Кодирование URL проводится с помощью символа '%' и двухсимвольного шестнадцатеричного значения, соответствующего данному символу в UTF-8. Например, 上海+中國 в UTF-8 будет закодирован для URL как %E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B. Строка ? and the Mysterians будет закодирована для URL как %3F+and+the+Mysterians или %3F%20and%20the%20Mysterians.

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

Ниже показаны закодированные значения для некоторых популярных символов:

Символ	Закодированное значение
Пробел	`%20`
"	`%22`
<	`%3C`
>	`%3E`
#	`%23`
%	`%25`
\|	`%7C`

Процентное кодирование текста, который вводит пользователь, может оказаться непростой задачей. Например, он может ввести адрес как "5th&Main St." Обычно URL необходимо создавать из отдельных частей, обрабатывая все вводимые пользователем данные как символьные литералы.

Кроме того, URL для всех веб-сервисов платформы Google Карт и Maps Static API могут содержать не более 16 384 символов. Для большинства служб этого размера более чем достаточно. но в некоторых случаях из-за ряда параметров длина URL может существенно увеличиться.

Правила использования API Google

Неправильно разработанные клиенты API могут создавать большую нагрузку на интернет и серверы. В этом разделе приведены рекомендации по работе с клиентами API. Соблюдение этих рекомендаций поможет избежать блокировки приложения из-за непреднамеренного злоупотребления API.

Экспоненциальная выдержка

В редких случаях с вашим запросом может что-то пойти не так. Вы можете получить код ответа HTTP 4xx или 5xx, или TCP-подключение может не установиться где-то между вашим клиентом и сервером Google. Часто стоит повторить запрос, поскольку следующий запрос может быть выполнен успешно, даже если предыдущий не удался. Однако не следует отправлять запросы на серверы Google слишком часто. Такое поведение может перегрузить сеть между клиентом и Google, что приведет к проблемам для многих пользователей.

Повторно пробовать лучше с возрастающими задержками между попытками. Задержка обычно увеличивается в геометрической прогрессии с каждой попыткой. Такой подход называется экспоненциальным откладыванием.

Например, приложение отправляет следующий запрос к Time Zone API:

https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1331161200&key=YOUR_API_KEY

В следующем примере на языке Python показано, как отправить запрос с экспоненциальным откладыванием:

import json
import time
import urllib.error
import urllib.parse
import urllib.request

# The maps_key defined in the following code isn't a valid Google Maps API key.
# You need to get your own API key.
# See https://developers.google.com/maps/documentation/timezone/get-api-key
API_KEY = "YOUR_KEY_HERE"
TIMEZONE_BASE_URL = "https://maps.googleapis.com/maps/api/timezone/json"


def timezone(lat, lng, timestamp):

    # Join the parts of the URL together into one string.
    params = urllib.parse.urlencode(
        {"location": f"{lat},{lng}", "timestamp": timestamp, "key": API_KEY,}
    )
    url = f"{TIMEZONE_BASE_URL}?{params}"

    current_delay = 0.1  # Set the initial retry delay to 100ms.
    max_delay = 5  # Set the maximum retry delay to 5 seconds.

    while True:
        try:
            # Get the API response.
            response = urllib.request.urlopen(url)
        except urllib.error.URLError:
            pass  # Fall through to the retry loop.
        else:
            # If the request didn't produce an IOError, parse the result.
            result = json.load(response)

            if result["status"] == "OK":
                return result["timeZoneId"]
            elif result["status"] != "UNKNOWN_ERROR":
                # Many API errors can't be fixed by a retry, such as
                # INVALID_REQUEST or ZERO_RESULTS. Don't retry these requests.
                raise Exception(result["error_message"])

        if current_delay > max_delay:
            raise Exception("Too many retry attempts.")

        print("Waiting", current_delay, "seconds before retrying.")

        time.sleep(current_delay)
        current_delay *= 2  # Increase the delay on each retry.


if __name__ == "__main__":
    tz = timezone(39.6034810, -119.6822510, 1331161200)
    print(f"Timezone: {tz}")

Убедитесь, что в цепочке вызовов приложения нет кода повторной попытки, который приводит к тому, что запросы отправляются слишком часто.

Синхронизированные запросы

Большое количество синхронизированных запросов к API Google может быть воспринято как распределенная атака типа "отказ в обслуживании" (DDoS) на инфраструктуру Google, и в этом случае будут приняты соответствующие меры. Чтобы избежать этой проблемы, убедитесь, что запросы API не синхронизируются между клиентами.

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

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

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

Не задавайте в качестве целевого времени другие распространенные моменты синхронизации, например начало часа или начало дня в полночь.

Обработка ответов

Поскольку точный формат отдельных ответов на запрос веб-сервиса не гарантируется (некоторые элементы могут отсутствовать или находиться в разных местах), не предполагайте, что формат, возвращаемый для любого заданного ответа, будет одинаковым для разных запросов. Вместо этого обработайте ответ и выберите подходящие значения с помощью выражений.

В этом разделе рассказывается, как динамически извлекать эти значения из ответов веб-сервисов.

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

Схема синтаксического анализа зависит от того, возвращаете ли вы выходные данные в формате JSON. Ответы в формате JSON, которые уже являются объектами JavaScript, можно обрабатывать в JavaScript на стороне клиента.