Начало работы

Разработчики из Европейской экономической зоны (ЕЭЗ)

Если ваш платежный адрес находится в Европейской экономической зоне, то с 8 июля 2025 года на использование вами Сервисов будут распространяться Условия использования платформы Google Карт для ЕЭЗ. Подробнее… Кроме того, Maps Static API больше не будет возвращать определенный контент. Подробнее…

Введение

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

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

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

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

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

• center (обязательный, если маркеры отсутствуют) – определяет центр карты, равноудаленный от всех ее краев. Этот параметр принимает местоположение в виде пары {широта,долгота}, разделенной запятой (например, "40.714728,-73.998672"), или в виде строки адреса (например, "city hall, new york, ny"), определяющей уникальное местоположение на поверхности Земли. Подробнее о местоположениях…
• 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 (необязательно) – определяет тип создаваемой карты. Существует несколько возможных значений maptype, включая roadmap, satellite, hybrid и terrain. Подробную информацию вы найдете в статье Типы карт Maps Static API.
• colorscheme (необязательно) – определяет цветовую схему карты. Допустимые значения: light (по умолчанию) и dark. Тёмная цветовая схема применяется к типам карт roadmap и terrain. Подробнее о режимах и типах карт…
• language (необязательно) – определяет язык, на котором будут отображаться надписи на фрагментах карты. Обратите внимание, что этот параметр поддерживается только для фрагментов некоторых стран. Если запрошенный язык не поддерживается для набора фрагментов, будет использоваться язык по умолчанию.
• region (необязательно) – определяет, какие границы следует показывать, с учетом геополитических особенностей. Принимает код региона, указанный как двухсимвольное значение национального домена верхнего уровня (ccTLD). Список поддерживаемых регионов приведен в статье Доступность сервисов платформы Google Карт.

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

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

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

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

Ограничение размера URL

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

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

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

Как указать местоположение

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

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

широта и долгота;

Широта и долгота задаются в виде чисел в текстовой строке с разделением запятыми и точностью до шести знаков после запятой. Например, "40.714728,-73.998672" — это допустимое значение геокода. Знаки после шестого отбрасываются.

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

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

Адреса

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

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

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

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

В примере ниже создается изображение статической карты для Беркли (Калифорния).

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. Это значение зависит от региона и может меняться со временем.

На уровне масштабирования 0 в Google Картах видна вся Земля. На каждом следующем уровне масштабирования точность увеличивается вдвое как по горизонтали, так и по вертикали. Подробную информацию об этом можно найти в документации по 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 (возвращает 1280 x 1280 пикселей)

В этом примере запрашивается фрагмент земной поверхности на экваторе на уровне масштабирования 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 x 200 пикселей. На ЖК-мониторе компьютера, который обычно отображает около 100 пикселей на дюйм, карта размером 200 x 200 будет иметь размер около 2 дюймов в каждом измерении.

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

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

Слишком маленькое	Слишком нечетко

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

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

150 x 150	150x150&scale=2

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

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

• первый определяет изображение размером 100 x 100 без значения scale. На компьютере она отображается правильно, но на мобильном устройстве текст слишком мелкий.
• во втором примере размер карты увеличен в два раза. На компьютере CSS вписывает ее в заданный элемент img размером 100 x 100, но при уменьшении изображения дороги и метки становятся слишком маленькими. На мобильном устройстве изображение имеет правильный размер, но дороги и метки снова неразборчивы.
• Третий запрос – карта размером 100 x 100 с scale=2. Изображение возвращается с разрешением 200 пикселей. На компьютере оно уменьшается до 100 пикселей, а мобильный браузер получает преимущества от дополнительного разрешения, возвращаемого API.

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

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

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

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

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

Изображения могут возвращаться в нескольких распространенных форматах веб-графики: 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 в настоящее время. Однако в некоторых случаях требуются непрогрессивные (базовые) изображения. В таких случаях можно использовать формат jpg-baseline, который не является прогрессивным.

Типы карт

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

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

Разницу между типами roadmap и terrain можно увидеть в этом примере кода.

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|... и т. д.

Набор markerStyles объявляется в начале объявления 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: (необязательно) – одна заглавная буква или цифра из набора {A–Z, 0–9}. (Требование использовать заглавные буквы появилось в этой версии API.) Обратите внимание, что параметр alphanumeric-character можно использовать только с маркерами по умолчанию и маркерами размера mid. Маркеры 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, например 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 пикселей (64 x 64 для квадратных изображений).

Примеры пользовательских значков

В примере 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

Пути Maps Static 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, путь отображается на экране в виде прямой линии. Значение по умолчанию – 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 JavaScript API, Maps Embed API, Maps SDK для Android или Maps SDK для iOS) и почему они не соответствуют вашим потребностям.
3. Скриншоты, макеты или примеры того, как вы будете использовать изображения большого размера.
4. Ориентировочное количество изображений большого размера, которое вы будете использовать в месяц.

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

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

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

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

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