Static API reference | 2GIS Documentation

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.

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

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

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 карта в портретном формате

c={lat},{lon}

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

Значения
  • lat широта
  • lon долгота
Примеры
  • c=55.7368,37.6326
  • c=-24.20649,135.32868

z={zoom}

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

Значения
  • zoom зум от 1 до 18
Примеры
  • z=9
  • z=15

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

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

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

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

Значения
  • 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

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

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 пикселей зелёным контуром и жёлтой заливкой с прозрачностью