Статические веб-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-адреса |
|---|---|---|
| Буквенно-цифровой | 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-адресов.