Лучшие практики использования Maps Static API

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

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

Что такое статический веб-API?

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

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

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

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

SSL/TLS-доступ

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

Создание действующего URL-адреса

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

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

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

Сводка допустимых символов URL-адреса
Набор персонажи использование URL-адреса
Буквенно-цифровой abcdefghijklm nopqrstuvwxyz ABCDEFGHIJKLM NOPQRSTUVWXYZ 0 1 2 3 4 5 6 7 8 9 Текстовые строки, использование схемы ( http ), порт ( 8080 ) и т. д.
незарезервировано - _ . ~ Текстовые строки
Сдержанный ! * ' ( ) ; : @ & = + $ , / ? % # [ ] Управляющие символы и/или текстовые строки

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

  • Персонажи, с которыми вы хотите работать, существуют за пределами указанного выше набора. Например, символы иностранных языков, такие как上海+中國необходимо кодировать с использованием вышеуказанных символов. По общепринятому соглашению пробелы (которые не разрешены в URL-адресах) также часто обозначаются знаком '+' .
  • Символы в приведенном выше наборе существуют как зарезервированные символы, но их нужно использовать буквально. Например, ? используется в URL-адресах для обозначения начала строки запроса; если вы хотите использовать строку «? и Мистерионы», вам нужно будет закодировать знак '?' характер.

Все символы, подлежащие кодированию 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

Преобразование URL-адреса, полученного в результате пользовательского ввода, иногда бывает непростой задачей. Например, пользователь может ввести адрес «5-я и Мейн-стрит». Как правило, вам следует создавать URL-адрес из его частей, рассматривая любой ввод пользователя как буквальные символы.

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