Static API reference

Точка входа static.maps.2gis.com, текущая версия 1.0, все параметры передаются через query, общий вид запроса:

GET /1.0?s={size}&c={center}&z={zoom}&pt={points}&ls={linestrings}&pn={polygons}

В ответ возвращается картинка в формате PNG либо ошибка с описанием проблемы.

Руководство

В документации в фигурных скобках указаны подставляемые значения, в квадратных - опциональные.

Координаты

Координаты широты и долготы точек необходимо указывать в градусах в формате ISO 6709.

Знак плюс + в положительных координатах можно не указывать либо необходимо закодировать для передачи в URL.

Цвета

Цвета линий и полигонов задаются в шестнадцатиричном формате RRGGBB[AA], где последовательно указаны компоненты красного, зелёного, синего цвета и опционально непрозрачность.

Префиксы # или 0x можно не указывать либо при использовании решётки # необходимо закодировать для передачи в URL.

Карта

Чтобы просто отобразить область карты достаточно указать её размер, центр и масштаб.

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

Size

s={width}x{height}[@{scale}]

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

Модификатор @2x включает HD режим для экранов Retina и других HiDPI. В этом случае фактический размер готовой карты будет в два раза больше запрашиваемого.

Значения

width ширина от 120 до 1280 пикселей
height высота от 90 до 1280 пикселей
scale
- 1x, по умолчанию
- 2x

Примеры

s=600x400 SD карта в альбомном формате
s=600x400@1x эквивалентно предыдущему примеру
s=200x300@2x HD карта в портретном формате

Center

c={lat},{lon}

Обязательно, если на карте отсутствуют объекты. Координаты центра карты.

Значения

lat широта
lon долгота

Примеры

c=55.7368,37.6326
c=-24.20649,135.32868

Zoom

z={zoom}

Обязательно, если на карте отсутствуют объекты. Уровень масштабирования карты.

Значения

zoom зум от 1 до 18

Примеры

z=9
z=15

Объекты

На карте можно нарисовать точки, линии и полигоны в различных стилях. Объекты во многом схожи с форматом GeoJSON.

Point & MultiPoint

На карте можно отобразить точки в виде кругов или пинов, использовать нумерацию или различные цвета и размеры, а также собственные маркера.

Standart point

pt={lat},{lon}[~k:{kind}][~c:{color}][~s:{size}]

Координаты точки, вид, цвет и размер стандартного маркера.

Значения

lat широта
lon долгота
kind вид маркера
- p пин, по умолчанию
- c круг
color цвет маркера
- rd красный
- oe оранжевый
- yw жёлтый
- gn зелёный
- be синий, по умолчанию
- pe фиолетовый
- pk розовый
- gy серый
- bk чёрный
size размер маркера
- s маленький, по умолчанию
- l большой

Примеры

pt=55.7368,37.6326 маленький синий пин по умолчанию
pt=55.7368,37.6326~k:c маленький синий круг
pt=55.7368,37.6326~c:gn маленький зелёный пин
pt=55.7368,37.6326~s:l большой синий пин
pt=55.7368,37.6326~k:c~c:gn~s:l большой зелёный круг

Numbered point

pt={lat},{lon}~n:{number}[~k:{kind}]

Координаты точки, номер и вид нумерованного маркера.

Значения

lat широта
lon долгота
number номер от 1 до 99
kind вид маркера
- p пин, по умолчанию
- c круг

Примеры

pt=55.7368,37.6326~n:1 пин по умолчанию с номером 1
pt=55.7368,37.6326~n:2~k:c круг с номером 2

Custom point by URL

pt={lat},{lon}~u:{url}[~a:{x},{y}]

Координаты точки, адрес и точка привязки своего маркера.

Таймаут на скачивание кастомного маркера 2 секунды. Лимит размера картинки 16 384 по заголовку ответа Content-Length, то есть 16 КБ. Полученное изображение кешируется на 2 часа.

Кастомные маркера не масштабируются автоматически в HD карте, необходимо самостоятельно контролировать режим карты и размер изображения маркера.

Значения

lat широта
lon долгота
url адрес картинки, закодированный для передачи в URL
x точка привязки по горизонтали от левого верхнего угла, в диапазоне от 0 до 1 является относительным значением от ширины, больше 1 - абсолютное значение в пикселях, по умолчанию 0.5 (центр)
y точка привязки по вертикали от левого верхнего угла, в диапазоне от 0 до 1 является относительным значением от высоты, больше 1 - абсолютное значение в пикселях, по умолчанию 0.5 (центр)

Примеры

pt=55.7368,37.6326~u:http%3A%2F%2Fexample.com%2Fimage.png кастомный маркер с привязкой по центру
pt=55.7368,37.6326~u:http%3A%2F%2Fexample.com%2Fimage.png~a:0.5,1 кастомный маркер с привязкой по серидине нижнего края (для ножек пинов)
pt=55.7368,37.6326~u:http%3A%2F%2Fexample.com%2Fimage.png~a:12,16 кастомный маркер с привязкой в точке 12,16 пикселей

Custom point by base64

pt={lat},{lon}~b:{base64}[~a:{x},{y}]

Координаты точки, base64 значение и точка привязки своего маркера.

Значения

lat широта
lon долгота
base64 картинка в стандартной кодировке base64, дополнительно закодированная для передачи в URL
x точка привязки по горизонтали от левого верхнего угла, в диапазоне от 0 до 1 является относительным значением от ширины, больше 1 - абсолютное значение в пикселях, по умолчанию 0.5 (центр)
y точка привязки по вертикали от левого верхнего угла, в диапазоне от 0 до 1 является относительным значением от высоты, больше 1 - абсолютное значение в пикселях, по умолчанию 0.5 (центр)

Примеры

pt=55.7368,37.6326~b:base64string кастомный маркер с привязкой по центру
pt=55.7368,37.6326~b:base64string~a:0.5,1 кастомный маркер с привязкой по серидине нижнего края (для ножек пинов)
pt=55.7368,37.6326~b:base64string~a:12,16 кастомный маркер с привязкой в точке 12,16 пикселей

MultiPoint

pt={lat1},{lon1}~{lat2},{lon2}[~{lat3},{lon3}...]

Любой вид точек можно отобразить в одном стиле на нескольких координатах за раз либо передать параметр pt несколько раз с нужными настройками.

Примеры

pt=55.7368,37.6326~55.7468,37.6226~55.7568,37.6126 три маленьких синих пина по умолчанию
pt=55.7368,37.6326&pt=55.7468,37.6226&pt=55.7568,37.6126 эквивалентно предыдущему примеру
pt=55.7368,37.6326~55.7468,37.6226~k:c~c:gn~s:l два больших зелёных круга
pt=55.7368,37.6326~55.7468,37.6226~u:http%3A%2F%2Fexample.com%2Fimage.png два кастомных маркера
pt=55.7368,37.6326~55.7468,37.6226~b:base64string два кастомных маркера

LineString & MultiLineString

На карте можно отобразить ломанные линии, управлять их цветом и толщиной.

LineString

ls={lat1},{lon1},{lat2},{lon2}...[~w:{weight}][~c:{color}]

Координаты точек, толщина и цвет линии.

Значения

lat широта
lon долгота
weight толщина линии в пикселях
color цвет линии

Примеры

ls=55.736,37.632,55.746,37.632 синяя линия по умолчанию
ls=55.736,37.632,55.746,37.632~w:7 линия с толщиной 7 пикселей
ls=55.736,37.632,55.746,37.632~c:ff0000 красная линия
ls=55.736,37.632,55.746,37.632~w:6~c:00ff00 зелёная линия с толщиной 6 пикселей

MultiLineString

ls={lat1},{lon1},{lat2},{lon2}...~{lat1},{lon1},{lat2},{lon2}...[~{lat1},{lon1},{lat2},{lon2}...]

Линии можно отобразить в одном стиле на нескольких координатах за раз либо передать параметр ls несколько раз с нужными настройками.

Примеры

ls=55.736,37.632,55.746,37.632~55.836,37.632,55.846,37.632 две синих линии по умолчанию
ls=55.736,37.632,55.746,37.632&pn=55.836,37.632,55.846,37.632 эквивалентно предыдущему примеру
ls=55.736,37.632,55.746,37.632~55.836,37.632,55.846,37.632~w:6~c:00ff00 две зелёных линии с толщиной 6 пикселей

Polygon & MultiPolygon

На карте можно отобразить полигоны без выреза, управлять их цветом и толщиной контура, а также цветом заливки.

Polygon

pn={lat1},{lon1},{lat2},{lon2},{lat3},{lon3}...[~w:{weight}][~c:{color}][~f:{fill}]

Координаты вершин, толщина и цвет контура, цвет заливки.

Значения

lat широта
lon долгота
weight толщина контура в пикселях
color цвет контура
fill цвет заливки

Примеры

pn=55.736,37.632,55.746,37.632,55.746,37.642 синий полигон с полупрозрачной заливкой по умолчанию
pn=55.736,37.632,55.746,37.632,55.746,37.642~w:7 полигон с толщиной контура 7 пикселей
pn=55.736,37.632,55.746,37.632,55.746,37.642~c:ff0000 полигон с красным контуром
pn=55.736,37.632,55.746,37.632,55.746,37.642~f:ff0000 полигон с красной сплошной заливкой
pn=55.736,37.632,55.746,37.632,55.746,37.642~f:ff0000a2 полигон с красной полупрозрачной заливкой
pn=55.736,37.632,55.746,37.632,55.746,37.642~w:6~c:00ff00~f:ffff00aa полигон с толщиной 6 пикселей зелёным контуром и жёлтой заливкой с прозрачностью

MultiPolygon

pn={lat1},{lon1},{lat2},{lon2},{lat3},{lon3}...~{lat1},{lon1},{lat2},{lon2},{lat3},{lon3}...[~{lat1},{lon1},{lat2},{lon2},{lat3},{lon3}...]

Полигоны можно отобразить в одном стиле на нескольких координатах за раз либо передать параметр pn несколько раз с нужными настройками.

Примеры

pn=55.736,37.632,55.746,37.632,55.746,37.642~55.836,37.632,55.846,37.632,55.846,37.642 два синих полигона с полупрозрачной заливкой по умолчанию
pn=55.736,37.632,55.746,37.632,55.746,37.642&pn=55.836,37.632,55.846,37.632,55.846,37.642 эквивалентно предыдущему примеру
pn=55.736,37.632,55.746,37.632,55.746,37.642~55.836,37.632,55.846,37.632,55.846,37.642~w:6~c:00ff00~f:ffff00aa два полигона с толщиной 6 пикселей зелёным контуром и жёлтой заливкой с прозрачностью