Руководство для разработчиков статических Google Карт

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

Примечание. Ограничения на использование интерфейса Google Static Maps API были изменены. Создание ключа API и его добавление в запрос позволяет отслеживать использование в Google Developers Console, а также при необходимости приобретать дополнительную квоту.

В этом документе приведено описание Google Static Maps API версии 2. Чтобы обновить URL-адреса версии 1, обратитесь к руководству по обновлению.

Пример

Следующий пример содержит URL-адрес изображения Google Static Maps API центральной части г. Нью-Йорк, которое представлено ниже:

https://maps.googleapis.com/maps/api/staticmap?center=Brooklyn+Bridge,New+York,NY&zoom=13&size=600x300&maptype=roadmap
&markers=color:blue%7Clabel:S%7C40.702147,-74.015794&markers=color:green%7Clabel:G%7C40.711614,-74.012318
&markers=color:red%7Clabel:C%7C40.718217,-73.998284
&key=YOUR_API_KEY

Обратите внимание, что вам не нужно выполнять какие-то особые операции, чтобы отобразить это изображение на веб-странице. JavaScript не требуется. Все, что потребовалось, это создать URL-адрес и вставить его в тег <img>. Можно разместить Google Google Static Maps API в любом месте веб-страницы, в котором можно располагать изображения.

Целевая аудитория

Этот документ предназначен для разработчиков веб-сайтов и мобильных приложений, которые хотят использовать изображения Google Static Maps API на веб-страницах или в приложениях для мобильных устройств. Документ содержит основные сведения по использованию API и справочные материалы по доступным параметрам.

Обзор

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

Изображение Google Static Maps API встраивается в атрибут src тега <img> или его эквивалент в других языках программирования. Если изображение Google Static Maps API используется вне веб-приложения (например, браузера), тогда ссылка должна быть включена с указанием на отображаемое место в веб-браузере или приложении Google Карты. (Это требование не распространяется на пользователей Google Maps API for Work.) Полную и актуальную информацию по этому требованию см. документе Условия использования приложений Google Карты/Google Планета Земля в разделе 10.1.1(h).

В этом документе описывается требуемый формат URL-адресов Google Static Maps API и доступные параметры. В нем также даны некоторые рекомендации и полезные советы для указания URL-адресов.

Параметры URL-адреса

URL-адрес Google Static Maps API должен иметь следующий формат:

https://maps.googleapis.com/maps/api/staticmap?parameters

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

https://maps.googleapis.com/maps/api/staticmap?parameters

Примечание. Google Static Maps API не поддерживает URL-адреса с пользовательским значком, в которых используется HTTPS; будет отображаться значок по умолчанию.

Независимо от того, будет ли использоваться протокол HTTP или HTTPS, некоторые параметры URL-адресов являются обязательными, тогда как другие – дополнительными. Все параметры разделяются амперсандами (&) в соответствии со стандартом URL-адресов. Ниже приведен список параметров и их возможные значения.

Внимание! При обсуждении параметров URL-адресов ниже используются примеры, которые для ясности приведены в их исходном виде до преобразования. Перед отправкой запросов в API-интерфейс к их параметрам должно быть применено соответствующее кодирование URL-адреса. Например, многие параметры в качестве разделителя используют вертикальную черту (|), которая при кодировании для окончательного URL-адреса должна иметь вид %7C, как это показано в примере в начале документа. Дополнительные сведения см. в разделе Создание допустимого URL-адреса.

Google Static Maps API определяет изображения карты с использованием следующих параметров URL-адреса:

Параметры местоположения

• center (обязательный параметр, если маркеры отсутствуют) – определяет центр карты, равноудаленный от всех ее краев. Этот параметр позволяет получить данные о местоположении либо в виде одной пары разделенных запятой координат{latitude,longitude} (например, "54.939320,37.450654"), либо как строчный адрес (например, "железнодорожный вокзал, г. Серпухов, МО"), указывающий местоположение на земной поверхности. Дополнительные сведения см ниже в разделе Местоположения.
• zoom (обязательный параметр, если маркеры отсутствуют) – определяет уровень масштабирования карты, который задает ее уровень увеличения. Этот параметр использует цифровое значение в соответствии с уровнем масштабирования выбранного региона. Дополнительные сведения см. ниже в разделе с описанием уровней масштабирования.

Параметры карты

• size (обязательный параметр) – определяет размеры прямоугольника изображения карты. В этот параметр передается строка следующего вида {horizontal_value}x{vertical_value}. Например, 500x400 означает карту с размером 500 пикселей по ширине на 400 пикселей по высоте. Для карт с шириной менее 180 пикселей будет отображаться логотип Google уменьшенного размера. На этот параметр влияет описанный далее параметр scale; конечный выходной размер представляет собой сочетание значений размера и масштаба.
• scale (дополнительный параметр) – влияет на количество возвращаемых пикселей. Параметр scale=2 возвращает в два раза больше пикселей, чем scale=1, при этом сохраняя ту же самую область покрытия и уровень детализации (то есть, содержимое карты не изменяется). Это полезно при разработке контента для отображения с высоким разрешением или при создании карты, предназначенной для печати. Значение по умолчанию – 1. Допустимые значения: 2 и 4 (4 доступно только для пользователей Google Maps API for Work). Дополнительные сведения см. в разделе Значения масштаба.
• format (дополнительный параметр) – определяет формат полученного изображения. По умолчанию Google Static Maps API создает изображения в формате PNG. Возможны также и другие форматы, включая GIF, JPEG и PNG. Выбор используемого формата зависит от того, каким образом вы планируете представить изображение. Формат JPEG обычно обеспечивает большую степень сжатия, тогда как изображения в форматах GIF и PNG более детальны. Дополнительные сведения см. в разделе Форматы изображения.
• maptype (дополнительный параметр) – определяет тип создаваемой карты. Имеются несколько возможных типов карты, включая roadmap, satellite, hybrid и terrain. Дополнительные сведения см. ниже в разделе Типы карты Google Static Maps API.
• language (дополнительный параметр) – определяет язык, используемый для отображения меток на листах карты. Обратите внимание, что этот параметр поддерживается только для некоторых листов карт стран; если для определенного набора листов тот или иной язык не поддерживается, для него будет использован язык, установленный по умолчанию.
• region (дополнительный параметр) – определяет соответствующие границы для отображения исходя из геополитической информации. Допускается код региона, указанный как значение из двух символов ccTLD (домен верхнего уровня).

Параметры объекта

• markers (дополнительный параметр) – определяет один или несколько маркеров для установки на изображении в указанных местах. Этот параметр принимает определение одного маркера с параметрами, разделенными вертикальной чертой (|). В один и тот же параметр markers можно поместить несколько маркеров, если для них используется одинаковый стиль; дополнительные маркеры других стилей можно добавить, используя добавочные параметры markers. Обратите внимание, что если вы предоставляете маркеры для карты, вам не нужно указывать параметры center и zoom, которые, как правило, являются обязательными. Дополнительные сведения см. ниже в разделе Маркеры Google Static Maps API.
• path (дополнительный параметр) – определяет один путь для двух или более соединенных точек для наложения на изображение в указанных местоположениях. В этот параметр передается строка, определяющую точки, где значения отдельных точек разделены вертикальной чертой (|). Можно предоставить дополнительные пути, добавив добавочные параметры path. Обратите внимание, что если вы предоставляете путь для карты, вам не нужно указывать параметры center и zoom, которые, как правило, являются обязательными. Дополнительные сведения см. ниже в разделе Пути Google Static Maps API.
• visible (дополнительный параметр) – указывает одно или несколько местоположений, которые должны оставаться видимыми на карте, хотя маркеры или другие отметки отображаться не будут. Используйте этот параметр, чтобы убедиться, что определенные объекты или местоположения на карте отображаются на Google Static Maps API.
• style (дополнительный параметр) – определяет настраиваемый стиль для изменения представления определенного объекта на карте (дороги, парка и т.д.). Этот параметр принимает аргументы feature и element, определяющие объекты для выбора и установки стиля, чтобы применить к этому выбору. Вы можете применить несколько стилей, добавив дополнительные параметры style. Дополнительные сведения см. далее в разделе Стили карт.

Параметры ключа и подписи

• key (обязательный параметр) – позволяет выполнять мониторинг использования API приложения в Google Developers Console, устанавливать ограничения квоты на ключ, а не на IP-адрес, а также позволяет Google связываться с вами относительно вашего приложения при необходимости. Дополнительные сведения см. в документе Получение ключа и подписи.
• signature (рекомендуемый параметр) – цифровая подпись, используемая для проверки наличия соответствующих прав у сайта, который создает запросы с помощью вашего ключа API. Дополнительные сведения см. в документе Получение ключа и подписи.

В своих запросах пользователи Google Maps API for Work должны указывать действительные параметры client и signature. Дополнительные сведения см. в разделе Аутентификация и авторизация Google Maps API for Work.

Ограничение длины URL-адреса

URL-адреса Google Static Maps API должны содержать не более 2048 символов. На практике вам, скорее всего, не понадобятся URL-адреса с большей длиной, если только вы не создаете сложные карты с большим количеством маркеров и путей. Тем не менее, обратите внимание, что браузеры или службы могут кодировать определенные символы для URL-адреса перед их отправкой к API-интерфейс, что в результате увеличивает длину адреса. Дополнительные сведения см. в разделе Создание допустимого URL-адреса.

Использование параметров

Google Static Maps API сравнительно прост в использовании, поскольку он состоит исключительно из параметризованного URL-адреса. В этом разделе описывается, как использовать эти параметры для создания URL-адресов.

Указание местоположений

Google Static Maps API должен быть в состоянии точно определять местоположения на карте, чтобы сфокусировать карту на необходимом местоположении (используя параметр center) или чтобы поместить какие-либо дополнительные метки (используя параметр markers) в определенных местоположениях на карте. Google Static Maps API использует числа (значения широты и долготы) или строки (адреса), чтобы указать эти местоположения. Эти значения определяют геокодированное местоположение.

Несколько параметров (например, markers и path) принимают несколько местоположений. В таких случаях местоположения разделяются вертикальной чертой (|).

Значения широты и долготы

Строки координат широты и долготы задаются с помощью цифр, разделенных запятой, точность которых составляет до 6 десятичных знаков. Например, "40.714728,-73.998672" является допустимым значением геокода. Точность более 6 десятичных знаков не учитывается.

Значения долготы основываются на расстоянии от Гринвича, Англия, места начала отсчета нулевого меридиана. Поскольку Гринвич расположен на широте 51.477222, мы можем указать значение center для параметра 51.477222,0, чтобы центрировать карту по Гринвичу:

Значения широты и долготы должны соответствовать действительному местоположению на земной поверхности. Широта может иметь значение от -90 до 90, а долгота – от -180 до 180. При указании неверного значения широты или долготы будет возвращена ошибка запроса.

Адреса

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

В любом параметре, который поддерживает использование широты и долготы, вместо них можно указать строку, обозначающую адрес. Google выполнит геокодирование адреса и предоставит службе Google Static Maps API значение широты и долготы для его использования при размещении маркеров или обозначении местоположений. Строка должна содержать символы преобразования URL, поэтому такой адрес как "железнодорожный вокзал, г. Серпухов, МО" должен быть преобразован, например, в "железнодорожный+вокзал,г.+Серпухов,МО".

Обратите внимание, что адреса могут отражать либо точные местоположения, например, адреса улиц, ломаные линии, например, шоссе с названиями, или многоугольные области, такие как города, страны или национальные парки. Для результатов, содержащих ломаные линии и многоугольные области, в качестве центра адреса сервер Google Static Maps API будет использовать центральные точки этих линий или областей. Если у вас есть какие-либо сомнения относительно того, как может быть геокодирован тот или иной адрес, вы можете протестировать его, используя это средство геокодирования.

В следующем примере демонстрируется создание Google Static Maps API для г. Беркли, шт. Калифорния:

https://maps.googleapis.com/maps/api/staticmap?center=Berkeley,CA&zoom=14&size=400x400&key=YOUR_API_KEY

Уровни масштабирования

Карты в приложении Google Карты имеют целочисленный "уровень масштабирования", который определяет разрешение текущего представления. Уровни масштабирования от 0 (наименьшее масштабирование, когда на одной карте отображается весь мир) до 21+ (с указанием улиц и отдельных зданий) могут быть использованы в рамках применяемого по умолчанию представления roadmap. Контуры зданий, где это возможно, отображаются на карте с уровнем масштабирования примерно 17. Это значение отличается в зависимости от области и может изменяться при получении новых данных.

Чтобы отобразить карту всего мира, Google Карты устанавливает уровень масштабирования 0. Каждый последующий уровень масштабирования удваивает точность как по горизонтали, так и по вертикали. Дополнительные сведения о том, как это происходит, содержатся в документации для Google Maps JavaScript API.

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

Если вы отправите запрос, чтобы получить уровень масштабирования, для которого отсутствуют листы карты, Google Static Maps API предоставит карту, отображающую максимальный уровень масштабирования, доступный для этого местоположения.

В приведенном ниже примере продемонстрированы 2 карты Манхэттена с одинаковым значением center, но с применением уровней масштабирования 12 и 14, соответственно:

https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&key=YOUR_API_KEY
https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=14&size=400x400&key=YOUR_API_KEY

  

Размеры изображений

Параметр size в сочетании с параметром center определяет область покрытия карты. Он также определяет выходной размер карты в пикселях при увеличении с использованием значения scale, которое по умолчанию установлено как 1.

В приведенной ниже таблице указаны максимальные допустимые значения для параметра size при каждом значении scale.

API	scale=1	scale=2	scale=4
Бесплатный	640x640	640x640 (возвращает 1280x1280 пикселей)	Недоступно.
Google Maps API for Work	2048x2048	1024x1024 (возвращает 2048x2048 пикселей)	512x512 (возвращает 2048x2048 пикселей)

В приведенном ниже примере выполняется запрос фрагмента земной поверхности у экватора с уровнем масштабирования 1:

https://maps.googleapis.com/maps/api/staticmap?center=0,0&zoom=1&size=400x50&key=YOUR_API_KEY

В приведенном ниже примере выполняется запрос небольшой карты размером 100x100 пикселей с центрированием на том же самом регионе. Обратите внимание на логотип Google меньшего размера:

https://maps.googleapis.com/maps/api/staticmap?center=0,0&zoom=1&size=100x100&key=YOUR_API_KEY

Значения масштаба

Параметр size Google Static Maps API определяет размер карты в пикселях таким образом, чтобы карта size=200x200 отображалась с размером 200х200 пикселей. На жидкокристаллических мониторах, где обычно отображается 100 ppi (пикселей на дюйм), карта 200x200 будет занимать около 2 дюймов (5 см) по высоте и ширине.

Тем не менее, все больше мобильных устройств оснащаются экранами высокого разрешения с плотностью пикселей более 300 ppi, что приводит к следующим эффектам.

• Размер изображения 200х200 пикселей уменьшается всего до 0,7 дюйма (1,7 см), в результате чего метки и значки будут слишком мелкими и трудноразличимыми.
• Изображение масштабируется (увеличивается) для повышения удобочитаемости, в результате чего оно становится смазанным или пикселизированным.

Слишком маленькое	Слишком размытое

При разработке для мобильных устройств используйте параметр scale API-интерфейса, чтобы получить изображения карты с высоким разрешением, которые устранят описанные выше проблемы. Значение scale умножается на size, чтобы определить фактический выходной размер изображения в пикселях без изменения области покрытия карты. (По умолчанию значение параметра scale равно 1; допустимые значения 1, 2 и 4 (только для пользователей Google Maps API for Work) ).

Например, значение масштаба 2 обеспечит ту же самую область покрытия, что и запрос без указания масштаба, но с вдвое большим количеством пикселей для каждого размера. Это включает в себя дороги и метки, поэтому они четко отображаются на небольших экранах высокого разрешения, а также при масштабировании браузером.

150x150	150x150&scale=2

Такое изображение также будет правильно отображаться в браузерах стационарных компьютеров, при вставке в тег img или div, когда высота и ширина устанавливаются с помощью CSS. Браузер уменьшит размер изображения до правильного без потери качества.

В приведенной ниже таблице показаны три разных запроса изображения.

• Первый для изображения 100x100 без указания значения масштаба. Оно правильно отображается на мониторе стационарного компьютера, но окажется слишком мало для использования на мобильном устройстве.
• Во втором запросе размер карты увеличен вдвое. На мониторе стационарного компьютера CSS подгоняет ее в соответствии с указанным элементом img 100x100, однако при уменьшении размера изображения дороги и метки становятся слишком мелкими. На мобильном устройстве изображение имеет правильный размер, но опять же, дороги и метки плохо различимы.
• В третьем запросе требуется карта 100x100 с параметром scale=2. Изображение отображается с детализацией 200 пикселей; монитор стационарного компьютера отлично уменьшает его масштаб, поэтому оно неотличимо от исходного запроса изображения 100х100, в то время как дополнительное разрешение, возвращаемое API-интерфейсом, повышает качество отображения в браузере мобильного устройства.

Устройство	100x100	200x200	100x100&scale=2
Стационарный компьютер (с height="100px" и width="100px" для тега img)
Высокое разрешение (смоделировано)

Совет. Мобильные платформы, такие как Android и iOS, позволяют приложениям поддерживать экраны высокого разрешения, указывая отдельные изображения для каждого разрешения. Параметр масштаба упрощает запрос изображения карты для экранов стандартного разрешения и обеспечивает соответствие карты экранам высокого разрешения, просто устанавливая значения scale=1 и scale=2, соответственно.

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

• Поддержка нескольких экранов в документации для разработчиков Android.
• Рекомендации на веб-сайте Webkit.org для разработки веб-сайтов с высокой плотностью пикселей.
• Supporting High-Resolution Screens в библиотеке разработчиков iOS Developer Library.

Форматы изображений

Предусмотрена поддержка нескольких распространенных форматов веб-графики: GIF, JPEG и PNG. Параметр format принимает одно из следующих значений:

• png8 или png (по умолчанию) – указывает 8-разрядный формат PNG.
• png32 – указывает 32-разрядный формат PNG.
• gif – указывает формат GIF.
• jpg – указывает формат сжатия JPEG.
• jpg-baseline – указывает непрогрессивный формат сжатия JPEG.

Как правило, форматы jpg и jpg-baseline обеспечивают наименьший размер изображения, хотя и с использованием сжатия "с потерями", которое может отрицательно сказаться на качестве изображения. Форматы gif, png8 и png32 обеспечивают сжатие без потерь.

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

Типы карт

Google Static Maps API создает карты нескольких форматов, которые перечислены ниже.

• roadmap (по умолчанию) – указывает стандартное изображение дорожной карты, как она обычно отображается на веб-сайте Google Карт. Если значение maptype не указано, по умолчанию Google Static Maps API обрабатывает листы roadmap.
• satellite – задает изображение спутникового снимка.
• terrain – задает изображение физической карты рельефа с отображением местности и растительности.
• hybrid – задает гибридное изображение спутникового снимка и дорожной карты с отображением прозрачного слоя с основными улицами и названиями мест на спутниковом снимке.

В приведенном ниже примере кода представлена разница между дорожной картой и картой местности.

https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=roadmap&key=YOUR_API_KEY
https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=terrain&key=YOUR_API_KEY

  

Гибридные карты используют спутниковые снимки и основные объекты дорожных карт для создания комбинированной карты. В следующих примерах представлены спутниковая и гибридная карты.

https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=satellite&key=YOUR_API_KEY
https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=hybrid&key=YOUR_API_KEY

  

Стили карт

Стили карт позволяют настроить вид стандартных карт Google, изменяя стиль изображения таких элементов как дороги, парки и районы застройки, чтобы отразить разные стили, которые могут использоваться на карте по умолчанию. Такие компоненты, также называемые объектами, можно выбирать и применять визуальные стили для их отображения (включая возможность скрыть их полностью). С помощью подобных изменений можно создать карту, где подчеркиваются определенные компоненты или дополнительное содержимое на связанной странице.

Настраиваемая карта со стилем включает в себя один или несколько указанных стилей, каждый из которых обозначен с использованием параметра style в URL-адресе запроса Google Static Maps API. Чтобы указать другие стили, следует передать дополнительные параметры style. Стиль состоит из выбора и нескольких правил, которые применяются к этому выбору. Правила указывают, какие визуальные изменения следует применить к выбору.

Каждое объявление параметра style включает в себя следующие аргументы, разделяемые вертикальной чертой ("|") в рамках объявления style.

• feature (дополнительный параметр) – указывает, какие объекты на карте должны быть выбраны для этого изменения стиля. (См. раздел Объекты на карте ниже.) Если не передан ни один аргумент для параметра feature, будут выбраны все объекты.
• element (дополнительный параметр) – указывает, какой комплект выбранных объектов следует выбрать. (См. раздел Элементы карты ниже.) Если не передан ни один аргумент параметра element, будут выбраны все элементы определенного объекта.
• Любой из следующих аргументов указывает правила, которые следует применить к приведенному выше выбору. Все правила применяются в том же порядке, в каком они отображаются в объявлении style. (См. раздел Правила стилей ниже.) После выбора объекта может применяться любое количество правил с учетом ограничений для стандартной длины URL-адреса, принятых для Google Static Maps API.

Примечание. Объявление параметра style должно содержать указание приведенных выше аргументов в изложенном порядке. Например, выбор объекта с двумя правилами должен иметь следующий вид:

style=feature:featureArgument|element:elementArgument|rule1:rule1Argument|rule2:rule2Argument

Объекты на карте

Карта состоит из набора объектов, таких как дороги или парки. На основе типов объектов формируется дерево категорий, корневым элементом которого является параметр feature:all. Ниже приведен список некоторых наиболее распространенных объектов.

• feature:all (по умолчанию) – выбирает все объекты на карте.
• feature:road – выбирает все дороги на карте.
• feature:landscape – выбирает все фоновые ландшафты на карте, которые чаще всего являются областью между дорогами, например. В городах ландшафт, как правило, состоит из районов застройки.

Полный список объектов, которые можно выделить на карте, приведен в Справочнике поGoogle Maps JavaScript API.

Некоторые категории типов объектов содержат подкатегории, названия которых отделяются точками (например, landscape.natural или road.local). Если указан родительский объект (например, road), тогда стили, которые применяются к этому выбору, будут применены ко всем дорогам, включая подкатегории.

Элементы объектов на карте

Как правило, некоторые объекты на карте также содержат различные элементы. Например, дорога состоит не только из линии (геометрическая часть) на карте, но также из текста названия этой дороги (ярлыков), связанного с картой. Элементы объектов выбираются путем объявления аргумента element. Поддерживаются следующие значения аргументов для элементов.

• element:all (по умолчанию) – выбираются все элементы объекта.
• element:geometry – выбираются только геометрические элементы объекта.
• element:labels – выбираются только текстовые ярлыки, связанные с объектом.

Если не передан ни один аргумент элемента, стили будут применены ко всем элементам определенного объекта на карте независимо от типа элемента.

Следующее объявление style позволяет выбрать ярлыки для всех местных дорог:

style=feature:road.local|element:labels

Правила стилей

Правила стилей представляют собой варианты форматирования, которые применяются к объектам и элементам, указанным в каждом объявлении style. Каждое объявление style должно содержать одну или несколько операций, разделяемых вертикальной чертой ("|"). Каждая операция указывает свое значение аргумента с помощью двоеточия (":"); при этом все операции применяются к выбору в том порядке, в котором они указаны.

В настоящее время поддерживаются следующие аргументы операций и принимающие значения:

• hue (шестнадцатеричное обозначение цвета RGB в формате 0xRRGGBB) – указывает базовый цвет для применения к выбору. (* См. примечание относительно использования ниже.)
• lightness – указывает процентное изменение яркости элемента (значение с плавающей запятой от -100 до 100). Отрицательные значения означают уменьшение яркости (-100 соответствует черному цвету), а положительные – увеличение яркости (+100 соответствует белому цвету).
• saturation – изменение интенсивности базового цвета элемента в процентах (значение с плавающей запятой от -100 до 100).
• gamma – применяемая к элементу гамма-коррекция (значение с плавающей запятой от 0,01 до 10,0, значение 1,0 означает отсутствие коррекции). Гамма-коррекция служит для нелинейного изменения яркости оттенков без влияния на значения для белого или черного цветов. Обычно гамма-коррекция используется для изменения контрастности нескольких элементов. Например, гамма-коррекцию можно применить для увеличения или уменьшения контраста между краями и внутренними частями элементов. Низкие значения гамма-коррекции (<1) увеличивают контраст, а высокие значения (>1) уменьшают его.
• inverse_lightness:true – просто инвертирует яркость.
• visibility (on, off или simplified) – указывает, отображается ли элемент на карте, и в каком виде. visibility:simplified – указывает, что карта должна автоматически упрощать представление этих элементов. (Например, на упрощенной дорожной сети может показываться меньше дорог.)

Правила стилей должны применяться в виде отдельных четких операций в том же порядке, в каком они отображаются в объявлении style. Порядок операций важен, потому что некоторые операции не совместимы друг с другом. Объекты или элементы, которые изменяются с помощью операций применения стилей обычно уже имеют собственный стиль. Если это так, операции выполняются на основе этих имеющихся стилей.

Обратите внимание, что для обозначения цветов в операциях применения параметров стилей используется модель оттенков, насыщенности цвета и яркости (HSL). Операции, определяющие цвет, часто используются в графическом дизайне. Оттенок определяет базовый цвет, насыщенность определяет его интенсивность, а яркость определяет относительное количество черного или белого в составе цвета. Все три значения HSL могут быть связаны со значениями RGB (и наоборот). Гамма-коррекция используется для изменения насыщенности в цветовом пространстве, как правило, для увеличения или уменьшения контрастности. Кроме того, модель HSL определяет цвет в пространстве координат, где hue (оттенок) означает ориентацию внутри цветового круга, тогда как насыщенность и яркость указывают амплитуды среди разных осей. Оттенки измеряются в цветовом пространстве RGB, которое подобно большинству других аналогичных пространств RGB, за исключением того, что в нем отсутствуют оттенки белого и черного.

Цветовой круг RGB

Примечание. Хотя в параметре hue (оттенок) для обозначения цвета используется шестнадцатеричный код RGB, это значение используется только для определения базового цвета, а не для его насыщенности или яркости, которые указываются отдельно при изменении процентного значения. Например, оттенок для чистого зеленого цвета может быть определен как hue:0x00ff00 или hue:0x000100, и оба оттенка будут идентичны. (Оба значения указывают на чистый зеленый в цветовой модели HSL.) Значения hue в формате RGB, содержащие в равных частях красный, зеленый и синий цвета (например, hue:0x0000000 (черный) или hue:0xffffff (белый) и все оттенки серого), не указывают оттенок, поскольку ни одно из этих значений не указывает ориентацию в пространстве координат HSL. Чтобы задать черный, белый или серый цвет, необходимо полностью убрать saturation (насыщенность) (добавить операцию saturation:-100) и вместо этого изменять параметр lightness (яркость).

При изменении существующих объектов, уже имеющих цветовую схему, изменение значения hue не меняет текущие значения saturation или lightness.

В приведенном ниже примере показана карта Бруклина, на которой цвет местных дорог изменен на светло-зеленый, а цвет жилых районов – на черный (обратите внимание, что в этом полностью рабочем примере разделители в виде прямой черты содержат правильное кодирование для URL; см. примечание выше):

https://maps.googleapis.com/maps/api/staticmap?size=512x512&zoom=15&center=Brooklyn&style=feature:road.local%7Celement:geometry%7Ccolor:0x00ff00%7Cweight:1%7Cvisibility:on&style=feature:landscape%7Celement:geometry.fill%7Ccolor:0x000000%7Cvisibility:on&style=feature:administrative%7Celement:labels%7Cweight:3.9%7Cvisibility:on%7Cinverse_lightness:true&style=feature:poi%7Cvisibility:simplified&key=YOUR_API_KEY

В следующем примере операции и упрощения используются для примерного представления атласа дорог США.

https://maps.googleapis.com/maps/api/staticmap?size=512x512&zoom=12&center=Chicago&format=png&style=feature:road.highway%7Celement:geometry%7Cvisibility:simplified%7Ccolor:0xc280e9&style=feature:transit.line%7Cvisibility:simplified%7Ccolor:0xbababa&style=feature:road.highway%7Celement:labels.text.stroke%7Cvisibility:on%7Ccolor:0xb06eba&style=feature:road.highway%7Celement:labels.text.fill%7Cvisibility:on%7Ccolor:0xffffff&key=YOUR_API_KEY

Маркеры

Параметр markers определяет набор из одного или нескольких маркеров в наборе мест. Каждый маркер, определенный в рамках одного объявления markers, должен использовать такой же визуальный стиль; при необходимости отобразить маркеры с разными стилями, укажите несколько параметров markers с разной информацией о стиле.

В параметр markers передается набор назначенных значений (дескрипторов маркеров) в следующем формате:

markers=markerStyles|markerLocation1| markerLocation2|... и т.д.

Набор markerStyles указывается в начале объявления параметра markers и включает в себя несколько (или ни одного) дескрипторов стиля, разделяемых вертикальной чертой (|), после которых указывается набор из одного или нескольких мест, также разделяемых вертикальной чертой (|).

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

Стили маркеров

Набор дескрипторов стилей маркеров – это набор назначенных значений, разделяемых вертикальной чертой (|). Этот дескриптор стиля определяет визуальные атрибуты, используемые при отображении маркеров в дескрипторе. Эти дескрипторы стилей содержат следующие назначения ключей или значений.

• size: (дополнительный параметр) указывает размер маркера из набора {tiny, mid, small}. Если параметр size не установлен, маркер будет отображен со своим стандартным размером, используемым по умолчанию.

• color: (дополнительный параметр) указывает 24-разрядное значение цвета (пример: color=0xFFFFCC) или предварительно установленный цвет из набора {black, brown, green, purple, yellow, blue, gray, orange, red, white}.

  Обратите внимание, что прозрачность (указывается с использованием шестнадцатеричных 32-разрядных значений цвета) не поддерживается для маркеров, хотя и поддерживается для путей.

• label: (дополнительный параметр) – указывает одно буквенно-числовое значение в верхнем регистре из набора {A-Z, 0-9}. (Ввод символов в верхнем регистре – новое требование для этой версии API-интерфейса.) Обратите внимание, что маркеры, используемые по умолчанию, и маркеры mid (средний размер) являются единственными маркерами, которые могут отображать параметр alphanumeric-character (буквенно-числовые символы). Маркеры tiny и small (очень маленький и маленький) не могут отображать буквенно-числовые символы.

Примечание. Вместо этих маркеров можно использовать собственные значки. (Дополнительные сведения см. ниже в разделе Собственные значки.)

Местоположения маркеров

Каждый дескриптор маркера должен включать в себя информацию об одном или нескольких местоположениях, которые обозначают, куда следует установить маркер на карте. Эти местоположения могут быть указаны в виде значений широты или долготы или виде адресов. Для разделения местоположений используется вертикальная черта (|).

Параметры местоположения определяют размещение маркера на карте. Если местоположение находится вне границ карты, этот маркер не будет отображен на созданном изображении в том случае, если указаны параметры center и zoom. Однако, если эти параметры не указаны, сервер Google Static Maps API автоматически создаст изображение, содержащее указанные маркеры. (См. далее раздел Неявное расположение.)

Ниже приведен пример объявления маркера. Обратите внимание, что один набор стилей объявляется в трех местоположениях:

https://maps.googleapis.com/maps/api/staticmap?center=Williamsburg,Brooklyn,NY&zoom=13&size=400x400&
markers=color:blue%7Clabel:S%7C11211%7C11206%7C11222&key=YOUR_API_KEY

Чтобы определить маркеры с разными стилями, необходимо указать, несколько параметров markers. Этот набор параметров markers определяет 3 маркера: один голубой маркер с меткой "S", установленный с координатами 62.107733 и -145.5419, один маленький зеленый маркер, установленный у "Delta Junction, AK", и один желтый маркер среднего размера с меткой "C" у "Tok, AK". Эти маркеры представлены в примере ниже.

https://maps.googleapis.com/maps/api/staticmap?center=63.259591,-144.667969&zoom=6&size=400x400\
&markers=color:blue%7Clabel:S%7C62.107733,-145.541936&markers=size:tiny%7Ccolor:green%7CDelta+Junction,AK\
&markers=size:mid%7Ccolor:0xFFFF00%7Clabel:C%7CTok,AK"&key=YOUR_API_KEY

Собственные значки

Вместо значков маркеров, предлагаемых Google, можно использовать собственные значки. Собственные значки указываются с помощью следующих дескрипторов для параметра markers:

• icon – указывает URL-адрес, используемый в виде собственного значка маркера. Допускаются изображения в форматах PNG, JPEG или GIF (рекомендуется PNG).
• shadow (по умолчанию используется значение true) – указывает, что служба Google Static Maps API должна создавать соответствующую тень для изображения. Эта тень зависит от отображаемой области изображения и его непрозрачности или прозрачности.

Параметр icon необходимо указать с использованием URL-адреса (который должен быть надлежащим образом закодирован). Вы можете использовать любой действительный URL-адрес или сервис для сокращения URL-адресов, например, http://goo.gl. Одним из преимуществ сервисов для сокращения URL-адресов является то, что они могут автоматически кодировать URL-адреса. Размер значков не должен превышать 4096 пикселей (64x64 для квадратных изображений), а служба Google Static Maps API поддерживает использование до 5 уникальных собственных значков для одного запроса. Обратите внимание, что в Google Static Maps API каждый из этих уникальных значков может быть использован несколько раз.

Точка привязки собственных значков с дескриптором shadow:true (используется по умолчанию) будет установлена по центру в нижней части указанного изображения значка, от которого отбрасывается тень. Значки без тени (с дескриптором shadow:false) должны располагаться по центру в указанных для них местах, поэтом их точки привязки устанавливаются по центру изображения.

В приведенном ниже примере интерфейс Google Chart API используется для создания собственных маркеров для отображения нескольких кафе в г. Нью-Йорк:

https://maps.googleapis.com/maps/api/staticmap?size=480x480&markers=
icon:http://chart.apis.google.com/chart?chst=d_map_pin_icon%26chld=cafe%257C996600%7C
224+West+20th+Street+NY%7C75+9th+Ave+NY%7C700+E+9th+St+NY&key=YOUR_API_KEY

Примечание. Представленные выше несколько уровней преобразования могут вызвать замешательство. Google Chart API использует вертикальную черту (|), чтобы разделить строки в своих параметрах URL-адреса. Поскольку этот символ недопустим для использования в URL-адресе (см. примечание выше), то при создании действительного URL-адреса диаграммы он преобразовывается в %7C. Теперь результат указан как строка в определении icon, однако он содержит символ % (полученный при преобразовании в %7C, описанном выше), который не может быть напрямую включен как данные в URL-адрес и должен быть преобразован в %25. В результате будет создан URL-адрес, содержащий %257C, что означает 2 уровня кодирования. Подобным образом URL-адрес диаграммы содержит символ &который, не может быть включен напрямую, поскольку при этом он может рассматриваться как разделитель для параметров URL-адреса для Google Static Maps API, поэтому он также должен быть перекодирован.

Вот несколько шагов для создания URL-адреса Google Static Maps API:

# Intended chld parameter:
chld=cafe|996600

# Embedded in a fully valid chart URL:
http://chart.apis.google.com/chart?chst=d_map_pin_icon&chld=cafe%7C996600

# Intended icon parameter, containing a fully valid URL:
markers=icon:http://chart.apis.google.com/chart?chst=d_map_pin_icon&chld=cafe%7C996600

# Embedded in a valid and unambiguous Google Static Maps API URL:
...&markers=icon:http://chart.apis.google.com/chart?chst=d_map_pin_icon%26chld=cafe%257C996600

Пути Google Static Maps API

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

path=pathStyles|pathLocation1|pathLocation2|... и т.д.

Обратите внимание, что обе точки пути отделены друг от друга с использованием вертикальной черты (|). Поскольку данные как о стиле, так и о точке разделяются вертикальной чертой, информация о стиле должна отображаться первой в любом дескрипторе пути. Если сервер Google Static Maps API обнаружит информацию о местоположении в дескрипторе пути, все другие параметры пути также будут считаться местоположениями.

Стили путей

Набор дескрипторов стилей путей – это серия задаваемых значений, разделяемых вертикальной чертой (|). Каждый такой дескриптор стиля определяет визуальные атрибуты, используемые при отображении пути. Эти дескрипторы стилей содержат следующие назначения ключей или значений.

• weight: (дополнительный параметр) – указывает толщину линии пути в пикселях. Если параметр weight не установлен, для толщины линии пути будет использовано значение по умолчанию (5 пикселей).

• color: (дополнительный параметр) – указывает для цвета либо 24-разрядное значение (пример: color=0xFFFFCC), либо 32-разрядное значение (пример: color=0xFFFFCCFF), либо использует цвет из набора {black, brown, green, purple, yellow, blue, gray, orange, red, white}.

  Когда используется шестнадцатеричное 32-разрядное значение, последние два символа указывают 8-разрядное значение альфа-прозрачности. Это значение может варьироваться от 00 (полная прозрачность) до FF (полная непрозрачность). Обратите внимание, что прозрачность поддерживается для путей, но не поддерживается для маркеров.

• fillcolor: (дополнительный параметр) – указывает, что путем отмечена многоугольная область, а также обозначает цвет заливки, который используется в виде наложения в пределах этой области. Набор последующих местоположений не должен представлять собой замкнутый контур – сервер Google Static Maps API автоматически соединит первую и последнюю точки. Тем не менее, обратите внимание, что любой штрих на внешней стороне области с примененной заливкой не будет замкнут, если только вы намеренно не укажете то же самое местоположение начала и конца.
• geodesic: (дополнительный параметр) – указывает, что запрошенный путь должен быть интерпретирован как геодезическая линия, соответствующая изгибу земной поверхности. Если установлено значение "false", проложенный путь на экране будет иметь вид прямой линии. По умолчанию используется значение false.

Ниже представлены некоторые примеры определений путей.

• Тонкая голубая линия, непрозрачность 50%: path=color:0x0000ff80|weight:1
• Сплошная красная линия: path=color:0xff0000ff|weight:5
• Сплошная толстая белая линия: path=color:0xffffffff|weight:10

Эти параметры стилей путей являются дополнительными. Если предпочтительнее использовать атрибуты по умолчанию, определение атрибутов путей можно пропустить; в этом случае будет задействован первый аргумент дескриптора пути вместо первой объявленной точки (местоположения).

Точки путей

Чтобы нарисовать путь, параметру path также необходимо передать одну или несколько точек. После этого Google Static Maps API проложит путь вдоль этих точек в указанном порядке. Каждый параметр pathPoint указывается в pathDescriptor с разделением вертикальной чертой |.

В приведенном ниже примере показана голубая линия пути, для которой по умолчанию используется непрозрачность 50%, проходящая по г. Нью-Йорк от Юнион-сквер до Таймс-сквер.

Ниже приведены характеристики параметра path:

path=color:0x0000ff|weight:5|40.737102,-73.990318|40.749825,-73.987963|40.752946,-73.987384|40.755823,-73.986397

В следующем примере определяется этот же путь вместо определения сплошной красной линии с непрозрачностью 100%:

Ниже приведены характеристики этого параметра path:

path=color:0xff0000ff|weight:5|40.737102,-73.990318|40.749825,-73.987963|40.752946,-73.987384|40.755823,-73.986397

В следующем примере определяется многоугольная область в пределах Манхэттена с несколькими перекрестками, переданными как местоположения:

Ниже приведены характеристики этого параметра path:

path=color:0x00000000|weight:5|fillcolor:0xFFFF0033|8th+Avenue+%26+34th+St,New+York,NY|\
8th+Avenue+%26+42nd+St,New+York,NY|Park+Ave+%26+42nd+St,New+York,NY,NY|\
Park+Ave+%26+34th+St,New+York,NY,NY

Обратите внимание, что сам путь установлен как невидимый, а для многоугольной области применена непрозрачность 15%.

Кодированные ломаные линии

Вместо набора местоположений путь можно объявить как кодированную ломаную линию, используя префикс enc: в объявлении местоположения для параметра path. Обратите внимание, что если пути для карты предоставляются в виде ломаной линии, вам не нужно указывать параметры center и zoom, которые, как правило, являются обязательными.

В приведенном ниже примере показан путь Аляскинской трассы от г. Доусон-Крик, Британская Колумбия, до г. Делта-Джанкшен, Аляска, с использованием кодированной ломаной линии:

https://maps.googleapis.com/maps/api/staticmap?size=400x400&path=weight:3%7Ccolor:orange%7Cenc:polyline_data&key=YOUR_API_KEY

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

В приведенном ниже примере показана многоугольная область для района Бруклин, г. Нью-Йорк:

https://maps.googleapis.com/maps/api/staticmap?size=400x400&path=fillcolor:0xAA000033%7Ccolor:0xFFFFFF00%7C
enc:encoded_data&key=YOUR_API_KEY

Области просмотра

Изображения могут указывать область просмотра, обозначая видимые местоположения с помощью параметра visibler. Параметр visible указывает службе Google Static Maps API создавать карту таким образом, чтобы существующие местоположения оставались видимыми. (Этот параметр может сочетаться с имеющимися маркерами или путями для обозначения также и видимой области.) Обозначение области просмотра таким способом устраняет необходимость указывать точный уровень масштабирования.

В приведенном ниже примере представлен запрос для создания карты, в центре которой находится г. Бостон, шт. Массачусетс, и на которой показаны Массачусетский технологический институт и Гарвардская площадь в г. Кембридже, шт. Массачусетс:

https://maps.googleapis.com/maps/api/staticmap?center=Boston,MA
&visible=77+Massachusetts+Ave,Cambridge,MA%7CHarvard+Square,Cambridge,MA&size=512x512&key=YOUR_API_KEY

Неявное расположение карты

Как правило, чтобы определить расположение и уровень масштабирования создаваемой карты, необходимо указать параметры URL-адреса center и zoom. Однако, если указаны параметры markers, path или visible, вместо этого Google Static Maps API может неявным образом определить правильные значения для центра и уровня масштабирования, с учетом положения этих элементов.

При наличии двух или более элементов Google Static Maps API определит необходимый центр и уровень масштабирования, предоставляя большие отступы для имеющихся элементов. В приведенном ниже примере показана карта, на которой указаны города Сан-Франциско, Окленд и Сан-Хосе в Калифорнии.

https://maps.googleapis.com/maps/api/staticmap?size=512x512&maptype=roadmap\
&markers=size:mid%7Ccolor:red%7CSan+Francisco,CA%7COakland,CA%7CSan+Jose,CA&key=YOUR_API_KEY

Устранение неполадок и поддержка

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

Google Static Maps API может отображать сообщение об ошибке или предупреждение в случае появления каких-либо проблем. Проверьте наличие предупреждений, в частности, если вы заметили, что на карте отсутствуют те или иные элементы. Также рекомендуется проверять предупреждения перед запуском нового приложения. Обратите внимание, что предупреждения могут не отображаться сразу, поскольку они появляются в заголовке HTTP. Дополнительные сведения см. в руководстве с описанием ошибок и предупреждений.

Ранее запросы Google Static Maps API обязательно должны были содержать параметр sensor, чтобы указать, использовался ли приложением датчик для определения местоположения пользователя. Этот параметр больше не используется.