Начать

Введение

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

Изображение Maps Static API встроено в атрибут src тега <img> или его эквивалент в других языках программирования.

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

Прежде чем начать

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

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

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

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

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

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

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

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

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

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

  • center ( обязательный , если маркеры отсутствуют) определяет центр карты, равноудаленный от всех краев карты. Этот параметр принимает местоположение в виде пары {широта,долгота}, разделенной запятыми (например, «40,714728,-73,998672»), или строкового адреса (например, «мэрия, Нью-Йорк, Нью-Йорк»), определяющего уникальное местоположение на поверхности земля. Дополнительную информацию см. в разделе «Местоположения» .
  • zoom ( требуется , если маркеры отсутствуют) определяет уровень масштабирования карты, который определяет уровень увеличения карты. Этот параметр принимает числовое значение, соответствующее уровню масштабирования желаемой области. Дополнительную информацию см. в разделе Уровни масштабирования .

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

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

Параметры функции

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

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

  • key ( обязательный ) позволяет вам отслеживать использование API вашим приложением в Google Cloud Console и гарантирует, что Google сможет связаться с вами по поводу вашего приложения, если это необходимо. Дополнительную информацию см. в разделе Использование ключей API с Maps Static API .
  • signature ( рекомендуется ) — это цифровая подпись, используемая для проверки того, что любой сайт, генерирующий запросы с использованием вашего ключа API, имеет на это право. Запросы без цифровой подписи могут завершиться неудачно. Дополнительные сведения см. в разделе Использование цифровой подписи .

Ограничение размера URL-адреса

Длина URL-адресов статического API Карт ограничена 16 384 символами. На практике вам, вероятно, не понадобятся более длинные URL-адреса, если только вы не создаете сложные карты с большим количеством маркеров и путей.

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

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

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

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

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

Широта и долгота

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

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

Гринвич, Англия

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

Адреса

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

В любом параметре, где вы можете указать широту/долготу, вы можете вместо этого указать строку, указывающую адрес . Google геокодирует адрес и предоставит службе Maps Static API значение широты и долготы для использования при размещении маркеров или указании местоположений. Строка должна иметь URL-кодировку , поэтому такие адреса, как «Сити-Холл, Нью-Йорк, Нью-Йорк», следует преобразовать, например, в «Сити+Холл,Нью+Йорк,Нью-Йорк».

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

В следующем примере создается статическое изображение карты Беркли, Калифорния: 

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

Беркли, Калифорния

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

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

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

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

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

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

  • 1: Мир
  • 5: Суша/континент
  • 10: Город
  • 15: Улицы
  • 20: Здания

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

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

Манхэттен ДалекийМанхэттен вблизи

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

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

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

scale=1 scale=2
640x640 640x640 (возвращает 1280x1280 пикселей)

В этом примере запрашивается «срез» Земли на экваторе при уровне масштабирования 1: 

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

Экватор

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

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

Малая карта экватора

Масштабные значения

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

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

  • Уменьшите размер изображения 200x200 пикселей всего до 0,7 дюйма, в результате чего метки и значки станут слишком маленькими для чтения; или
  • Масштабируйте (увеличьте) изображение, чтобы улучшить его разборчивость, в результате чего изображение становится нечетким или пиксельным.
Слишком маленький Слишком нечетко

При разработке для мобильных устройств вы можете использовать параметр scale API, чтобы возвращать изображения карт с более высоким разрешением, которые решают описанные выше проблемы. Значение scale умножается на size для определения фактического выходного размера изображения в пикселях без изменения зоны покрытия карты. Значение scale по умолчанию — 1; принятые значения — 1 и 2.

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

150х150 150x150&масштаб=2

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

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

  • Первый предназначен для изображения размером 100x100 без указания значения масштаба. Он правильно отображается на рабочем столе, но слишком мал для чтения на мобильном устройстве.
  • Второй удваивает размер карты. На рабочем столе CSS помещает его в указанный элемент img размером 100x100, но при уменьшении размера изображения дороги и метки становятся слишком маленькими. На мобильном устройстве изображение правильного размера, но дороги и надписи опять же неразборчивы.
  • Третий запрос — карта размером 100x100 с scale=2 . Изображение возвращается с детализацией 200 пикселей; настольный компьютер идеально масштабирует его, так что он неотличим от исходного запроса размером 100x100, а мобильный браузер получает выгоду от дополнительного разрешения, возвращаемого API.
Запросы изображений
Устройство 100x100 200x200 100x100&scale=2
Рабочий стол
(с height="100px" и
width="100px" на
тег img )
Высокое разрешение
(смоделировано)

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

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

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

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

В этих примерах запрашиваются карты в форматах gif и png :

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

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

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

Типы карт

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

  • roadmap (по умолчанию) определяет стандартное изображение дорожной карты, которое обычно отображается на веб-сайте Google Maps. Если значение maptype не указано, Maps Static 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&signature=YOUR_SIGNATURE
https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=terrain&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Нормальная карта МанхэттенаКарта местности Манхэттена

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

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

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

Стилизованные карты

Настройте представление стандартной карты Google, применив собственные стили. См. руководство по стилизованным картам .

Маркеры

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

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

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

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

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

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

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

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

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

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

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

Масштабирование маркера

Значение scale умножается на размер изображения маркера, чтобы получить фактический выходной размер маркера в пикселях. Значение шкалы по умолчанию — 1; принятые значения: 1, 2 и 4.

Ограничение размера изображений в пикселях применяется после применения масштабирования. Например, если для маркера установлено значение scale:2 , то размер маркера может превышать максимальный размер в 4096 пикселей, если после масштабирования он уменьшится до менее 4096 пикселей. Используйте масштабирование маркеров в сочетании с масштабированием карты при отображении карт с более высоким разрешением.

Расположение маркеров

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

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

Параметры местоположения определяют местоположение маркера на карте. Если местоположение находится за пределами карты, этот маркер не появится на построенном изображении при условии, что указаны параметры center и zoom . Однако если эти параметры не указаны, сервер Maps Static 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&signature=YOUR_SIGNATURE

Три почтовых индекса Бруклина

Чтобы определить маркеры с разными стилями, нам необходимо указать несколько параметров markers . Этот набор параметров markers определяет три маркера: один синий маркер с надписью «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&signature=YOUR_SIGNATURE

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

Пользовательские значки

Вместо использования значков маркеров Google вы можете использовать свои собственные значки. Пользовательские значки задаются с помощью дескриптора icon в параметре markers . Например:

markers=icon: URLofIcon | markerLocation

Укажите icon , используя URL-адрес (который должен быть закодирован в URL-адресе ). Вы можете использовать URL-адреса, созданные службами сокращения URL-адресов, например https://goo.gl . Большинство сервисов сокращения URL-адресов имеют преимущество автоматического кодирования URL-адресов.

Вы можете указать точку привязки для пользовательского значка. Точка привязки задает расположение значка относительно указанных местоположений markers . По умолчанию опорной точкой пользовательского значка является центр нижней части изображения значка. Вы можете указать другую точку привязки, используя дескриптор anchor в сочетании со icon . Задайте anchor в виде точки X,Y значка (например, 10,5 ) или в качестве предопределенного выравнивания, используя одно из следующих значений: top , bottom , left , right , center , topleft , topright , bottomleft или bottomright . Например:

markers=anchor:bottomright|icon: URLofIcon | markerLocation1 | markerLocation2

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

Формат значка:

  • Изображения значков могут быть в форматах PNG, JPEG или GIF, но рекомендуется PNG.
  • Максимальный размер значков может достигать 4096 пикселей (64x64 для квадратных изображений).
Примеры пользовательских значков

В примере 1 создаются пользовательские значки и позиционируются значки с помощью привязок. 

https://maps.googleapis.com/maps/api/staticmap?&size=600x400&style=visibility:on
&style=feature:water%7Celement:geometry%7Cvisibility:on
&style=feature:landscape%7Celement:geometry%7Cvisibility:on
&markers=anchor:32,10%7Cicon:https://goo.gl/5y3S82%7CCanberra+ACT
&markers=anchor:topleft%7Cicon:http://tinyurl.com/jrhlvu6%7CMelbourne+VIC
&markers=anchor:topright%7Cicon:https://goo.gl/1oTJ9Y%7CSydney+NSW&key=YOUR_API_KEY
&signature=YOUR_SIGNATURE

Три австралийских города, разные значки с якорями.

В примере 2 создаются те же пользовательские значки, что и в примере 1, но не задаются положения значков с помощью привязок, а используется привязка по умолчанию в центре нижней части. 

https://maps.googleapis.com/maps/api/staticmap?&size=600x400&style=visibility:on
&style=feature:water%7Celement:geometry%7Cvisibility:on
&style=feature:landscape%7Celement:geometry%7Cvisibility:on
&markers=icon:https://goo.gl/5y3S82%7CCanberra+ACT
&markers=icon:http://tinyurl.com/jrhlvu6%7CMelbourne+VIC
&markers=icon:https://goo.gl/1oTJ9Y%7CSydney+NSW&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Три австралийских города, разные значки с расположением по умолчанию.

Пути к статическим API карт

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

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

Обратите внимание, что обе точки пути отделены друг от друга символом вертикальной черты ( | ). Поскольку и информация о стиле, и информация о точках разделяются символом вертикальной черты, информация о стиле должна появляться первой в любом дескрипторе пути. Как только сервер Maps Static 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 : (необязательно) указывает, что путь отмечает многоугольную область, и указывает цвет заливки, который будет использоваться в качестве наложения внутри этой области. Следующий набор локаций не обязательно должен быть «замкнутым» циклом; Сервер Maps Static API автоматически соединит первую и последнюю точки. Однако обратите внимание, что любой штрих на внешней стороне закрашенной области не будет закрыт, если вы специально не укажете одно и то же начальное и конечное местоположение.
  • geodesic : (необязательно) указывает, что запрошенный путь следует интерпретировать как геодезическую линию, повторяющую кривизну Земли. Если установлено значение false, путь отображается как прямая линия в пространстве экрана. По умолчанию ложь.

Некоторые примеры определений путей:

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

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

Точки пути

Чтобы нарисовать путь, параметру path также необходимо передать две или более точки. Затем Maps Static 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 .

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

https://maps.googleapis.com/maps/api/staticmap
?size=400x400&center=59.900503,-135.478011&zoom=4
&path=weight:3%7Ccolor:orange%7Cenc:_fisIp~u%7CU%7D%7Ca@pytA_~b@hhCyhS~hResU%7C%7Cx@oig@rwg@amUfbjA%7Df%5BroaAynd@%7CvXxiAt%7BZwdUfbjAewYrqGchH~vXkqnAria@c_o@inc@k%7Bg@i%60%5Do%7CF%7DvXaj%5Ch%60%5Dovs@?yi_@rcAgtO%7Cj_AyaJren@nzQrst@zuYh%60%5Dv%7CGbldEuzd@%7C%7Cx@spD%7CtrAzwP%7Cd_@yiB~vXmlWhdPez%5C_%7BKm_%60@~re@ew%5ErcAeu_@zhyByjPrst@ttGren@aeNhoFemKrvdAuvVidPwbVr~j@or@f_z@ftHr%7BZlwBrvdAmtHrmT%7BrOt%7BZz%7DE%7Cc%7C@o%7CLpn~AgfRpxqBfoVz_iAocAhrVjr@rh~@jzKhjp@%60%60NrfQpcHrb%5Ek%7CDh_z@nwB%7Ckb@a%7BR%7Cyh@uyZ%7CllByuZpzw@wbd@rh~@%7C%7CFhqs@teTztrAupHhyY%7Dt%5Dhuf@e%7CFria@o%7DGfezAkdW%7C%7D%5BocMt_Neq@ren@e~Ika@pgE%7Ci%7CAfiQ%7C%60l@uoJrvdAgq@fppAsjGhg%60@%7ChQpg%7BAi_V%7C%7Cx@mkHhyYsdP%7CxeA~gF%7C%7D%5Bmv%60@t_NitSfjp@c%7DMhg%60@sbChyYq%7De@rwg@atFff%7D@ghN~zKybk@fl%7DA%7DcPftcAite@tmT__Lha@u~DrfQi%7DMhkSqyWivIumCria@ciO_tHifm@fl%7DA%7Brc@fbjAqvg@rrqAcjCf%7Ci@mqJtb%5Es%7C@fbjA%7BwDfs%60BmvEfqs@umWt_Nwn%5Epen@qiBr%60xAcvMr%7BZidg@dtjDkbM%7Cd_@
&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Аляска шоссе

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

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

https://maps.googleapis.com/maps/api/staticmap
?size=400x400&center=40.653279,-73.959816&zoom=11
&path=fillcolor:0xAA000033%7Ccolor:0xFFFFFF00%7Cenc:%7DzswFtikbMjJzZ%7CRdPfZ%7DDxWvBjWpF~IvJnEvBrMvIvUpGtQpFhOQdKpz%40bIx%7BA%7CPfYlvApz%40bl%40tcAdTpGpVwQtX%7Di%40%7CGen%40lCeAda%40bjA%60q%40v%7D%40rfAbjA%7CEwBpbAd_%40he%40hDbu%40uIzWcWtZoTdImTdIwu%40tDaOXw_%40fc%40st%40~VgQ%7C%5BuPzNtA%60LlEvHiYyLs%5EnPhCpG%7DSzCNwHpz%40cEvXg%40bWdG%60%5DlL~MdTmEnCwJ%5BiJhOae%40nCm%5B%60Aq%5DqE_pAaNiyBuDurAuB%7D%7DAy%60%40%7CEKv_%40%3F%7C%5BqGji%40lAhYyH%60%40Xiw%40tBerAs%40q%5DjHohAYkSmW%3FaNoaAbR%7DLnPqNtMtIbRyRuDef%40eT_z%40mW_Nm%7CB~j%40zC~hAyUyJ_U%7BZ%3F%3FcPvg%40%7Ds%40sHsc%40_z%40cj%40kp%40YePoNyYyb%40_iAyb%40gBw%5EbOokArcA%7DGwJuzBre%40i%5Ctf%40sZnd%40oElb%40hStW%7B%5Dvv%40%3F%3Fkz%40~vAcj%40zKa%60Atf%40uQj_Aee%40pU_UrcA
&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Бруклинская кодированная полилиния с подписью

Обзорные экраны

Изображения могут указывать область просмотра , указав видимые местоположения с помощью visible . visible параметр указывает службе Maps Static 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&signature=YOUR_SIGNATURE

Карта Кембриджа

Неявное позиционирование карты

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

При предоставлении двух или более элементов Maps Static 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&signature=YOUR_SIGNATURE

Дорожная карта

Большие размеры изображений

Если вам нужны изображения размером более 640 x 640 пикселей (или 1280 x 1280 пикселей со значением масштаба 2), обратитесь в службу поддержки и предоставьте следующую информацию:

  1. Ваш вариант использования и почему вам нужны изображения большого размера.
  2. Рассматривали ли вы возможность использования других API платформы Google Maps (API JavaScript Maps, API Maps Embed, Maps SDK для Android или Maps SDK для iOS) и почему они не соответствуют вашим потребностям.
  3. Скриншоты, макеты или примеры того, как вы будете использовать изображения большого размера.
  4. Примерное ежемесячное использование изображений большого размера.

Мы рассмотрим ваш запрос на основе предоставленной вами информации и определим, соответствует ли ваш вариант использования Условиям использования платформы Google Карт .

Максимальный размер, который мы можем предоставить, составляет 2048 x 2048 пикселей.

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

Дополнительную информацию об использовании Maps Static API можно найти на странице поддержки .

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