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

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

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

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

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

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

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

Примечание. Для всех приложений Maps Static API требуется аутентификация. Подробнее об учетных данных для аутентификации…

Доступ по протоколу TLS

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

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

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

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

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

При создании действительного 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.

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

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

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

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