Все готово!

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

Активация Google Static Maps API

Чтобы помочь вам освоиться, мы покажем, как выполнить некоторые необходимые действия в консоли разработчика Google:

  1. Создание или выбор проекта
  2. Активация Google Static Maps API
  3. Создание соответствующих ключей

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

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

Примечание. Ограничения на использование интерфейса Google Static Maps API были изменены. Создание ключа API и его добавление в запрос позволяет отслеживать использование в Google API 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 Maps. (Это требование не распространяется на пользователей Google Maps APIs Premium Plan.) Полную и актуальную информацию по этому требованию см. документе Условия использования приложений Google Maps/Google Earth в разделе 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

Независимо от того, будет ли использоваться протокол 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 APIs Premium Plan). Дополнительные сведения см. в разделе Значения масштаба.
  • 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 API Console и обеспечивает доступ к значительной бесплатной ежедневной квоте, а также позволяет Google в случае необходимости связываться с вами относительно вашего приложения. Дополнительные сведения см. в документе Получение ключа и подписи.
  • signature (рекомендуемый параметр) – цифровая подпись, используемая для проверки наличия соответствующих прав у сайта, который создает запросы с помощью вашего ключа API. Примечание. При включенной тарификации требуется цифровая подпись. Если вы превысите бесплатный ежедневный лимит загрузок карт, то до конца этого дня дополнительные загрузки карт будут платными. Тарифицируемые загрузки карт без цифровой подписи выполняться не будут. Дополнительные сведения см. в документе Получение ключа и подписи.

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

Пользователи с лицензией на ранее выпускавшийся продукт Google Maps APIs for Work должны включать в свои запросы действующие параметры client и signature вместо параметра key. Подробнее см. раздел Идентификаторы и подписи клиента на странице "Получение ключа и подписи".

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

URL-адреса Google Static Maps API должны содержать не более 8192 символов. На практике вам, скорее всего, не понадобятся 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 Maps имеют целочисленный "уровень масштабирования", который определяет разрешение текущего представления. Уровни масштабирования от 0 (наименьшее масштабирование, когда на одной карте отображается весь мир) до 21+ (с указанием улиц и отдельных зданий) могут быть использованы в рамках применяемого по умолчанию представления roadmap. Контуры зданий, где это возможно, отображаются на карте с уровнем масштабирования примерно 17. Это значение отличается в зависимости от области и может изменяться при получении новых данных.

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

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

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

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

  • 1: Мир
  • 5: Континент
  • 10: Город
  • 15: Улицы
  • 20: Здания

В приведенном ниже примере продемонстрированы 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 APIs Premium Plan 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 APIs Premium Plan) ).

Например, значение масштаба 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, соответственно.

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

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

Предусмотрена поддержка нескольких распространенных форматов веб-графики: 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 Maps. Если значение 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

Спутниковая карта Манхэттена  Карта местности Манхэттена

Стили карт

См. руководство по стилизации карт.

Маркеры

Параметр 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

3 индекса в Бруклине

Чтобы определить маркеры с разными стилями, необходимо указать, несколько параметров 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

3 города на Аляске, разные маркеры

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

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

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

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

Точка привязки настраиваемого значка устанавливается как центр нижней границы изображения.

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

https://maps.googleapis.com/maps/api/staticmap?size=480x480&markers=
icon:https://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:
https://chart.apis.google.com/chart?chst=d_map_pin_icon&chld=cafe%7C996600

# Intended icon parameter, containing a fully valid URL:
markers=icon:https://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:https://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, чтобы указать, использовался ли приложением датчик для определения местоположения пользователя. Этот параметр больше не используется.

Оставить отзыв о...

Текущей странице
Google Static Maps API
Нужна помощь? Обратитесь в службу поддержки.