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

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

Введение

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"), или в виде строки адреса (например, "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.
  • language (необязательно) – определяет язык, на котором будут показываться ярлыки на фрагментах карты. Обратите внимание, что этот параметр поддерживается только для некоторых фрагментов карты. Если запрошенный язык не поддерживается для набора фрагментов, будет использоваться язык по умолчанию для этого набора.
  • region (необязательно) – определяет границы, которые следует показывать с учетом геополитической ситуации. Принимает код региона, указанный как двухсимвольное значение ccTLD (домен верхнего уровня). Список поддерживаемых регионов приведен в статье Доступность сервисов платформы Google Карт.

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

  • map_id (необязательно) – идентификатор определенной карты. Идентификатор карты связывает карту с определенным стилем или функцией и должен принадлежать тому же проекту, что и ключ API, используемый для инициализации карты. Подробнее об использовании идентификаторов карт…
  • markers (необязательно) – определяет один или несколько маркеров, которые нужно добавить на изображение в указанных местах. Этот параметр принимает одно определение маркера с параметрами, разделенными вертикальной чертой (|). В одном параметре markers можно разместить несколько маркеров, если они имеют одинаковый стиль. Чтобы добавить маркеры других стилей, добавьте дополнительные параметры markers. Обратите внимание, что если вы добавили маркеры на карту, вам не нужно указывать параметры center и zoom, которые обычно являются обязательными. Подробную информацию вы найдете в статье Маркеры в Maps Static API.
  • path (необязательно) – определяет один путь из двух или более соединенных точек, который будет наложен на изображение в указанных местах. Этот параметр принимает строку определений точек, разделенных вертикальной чертой (|), или кодированную ломаную линию с префиксом enc: в объявлении местоположения пути. Вы можете указать дополнительные пути, добавив параметры path. Обратите внимание, что если вы укажете путь к карте, вам не нужно будет задавать параметры center и zoom, которые обычно являются обязательными. Подробную информацию вы найдете в статье Пути в Maps Static API.
  • 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 будет использовать в качестве центра адреса среднюю точку линии или области. Если вы не уверены, как будет геокодирован адрес, проверьте его с помощью утилиты геокодирования.

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

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 (возвращает изображение размером 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 API, чтобы возвращать изображения карт с более высоким разрешением, которые решают описанные выше проблемы. Значение параметра 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 пикселей, а в мобильном браузере показывается в исходном разрешении.
Запросы изображений
Устройство 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 Карт. Если значение 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.) Обратите внимание, что только маркеры по умолчанию и маркеры размером 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

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

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

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

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

Вместо значков маркеров 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 пикселей (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

Аляскинская трасса

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

Пример многоугольной области, с помощью которой отмечен Бруклин в Нью-Йорке:

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. Дополнительную информацию вы найдете в руководстве по ошибкам и предупреждениям.