Static API reference
Точка входа static.maps.2gis.com
, текущая версия 1.0
, все параметры передаются через query
, общий вид запроса:
GET /1.0?s={size}&c={center}&z={zoom}&g={geojson}&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 (RFC 7946).
Point & MultiPoint
На карте можно отобразить точки в виде кругов или пинов, использовать нумерацию или различные цвета и размеры, а также собственные маркера.
Standard 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 до 99kind
вид маркераp
пин, по умолчаниюc
круг
Примеры
pt=55.7368,37.6326~n:1
пин по умолчанию с номером 1pt=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
адрес картинки, закодированный для передачи в URLx
точка привязки по горизонтали от левого верхнего угла, в диапазоне от 0 до 1 является относительным значением от ширины, больше 1 - абсолютное значение в пикселях, по умолчанию 0.5 (центр)y
точка привязки по вертикали от левого верхнего угла, в диапазоне от 0 до 1 является относительным значением от высоты, больше 1 - абсолютное значение в пикселях, по умолчанию 0.5 (центр)
Примеры
pt=55.7368,37.6326~u:http://example.com/image.png
кастомный маркер с привязкой по центруpt=55.7368,37.6326~u:http://example.com/image.png~a:0.5,1
кастомный маркер с привязкой по серидине нижнего края (для ножек пинов)pt=55.7368,37.6326~u:http://example.com/image.png~a:12,16
кастомный маркер с привязкой в точке 12,16 пикселей
Custom point by base64
pt={lat},{lon}~b:{base64}[~a:{x},{y}]
Координаты точки, base64 значение и точка привязки своего маркера.
Кастомные маркера не масштабируются автоматически в HD карте, необходимо самостоятельно контролировать режим карты и размер изображения маркера.
Значения
lat
широтаlon
долготаbase64
картинка в стандартной кодировке base64, дополнительно закодированная для передачи в URLx
точка привязки по горизонтали от левого верхнего угла, в диапазоне от 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 пикселей зелёным контуром и жёлтой заливкой с прозрачностью
GeoJSON
На карте можно отобразить любые объекты по спецификации GeoJSON (RFC 7946) и стилизовать их в полях properties
аналогично параметрам в URL.
Объекты передаются в параметре g
и их необходимо закодировать для передачи в URL.
Geometry
RFC 7946, Section 3.1, Geometry Object
Поддерживаются все типы объектов геометрий такие как: Point, MultiPoint, LineString, MultiLineString, Polygon (без вырезов), MultiPolygon (без вырезов) и GeometryCollection.
Стили в данном случае используется по умолчанию.
Примеры
- точка
{
"type": "Point",
"coordinates": [ 82.91871, 55.03652 ]
}
- линия
{
"type": "LineString",
"coordinates": [
[ 82.91871, 55.03652 ],
[ 82.92131, 55.02711 ],
[ 82.92698, 55.02470 ]
]
}
- коллекция из точки и линии
{
"type": "GeometryCollection",
"geometries": [{
"type": "Point",
"coordinates": [ 82.91871, 55.03652 ]
}, {
"type": "LineString",
"coordinates": [
[ 82.91871, 55.03652 ],
[ 82.92131, 55.02711 ],
[ 82.92698, 55.02470 ]
]
}]
}
Feature
RFC 7946, Section 3.2, Feature Object
Feature позволяет геометриям добавить свойства для стилизации.
Standard Point & MultiPoint
Поддерживается стилизация вида, цвета и размера стандартного маркера.
Properties
{
"k": "{kind}",
"c": "{color}",
"s": "{size}"
}
kind
вид маркераp
пин, по умолчаниюc
круг
color
цвет маркераrd
красныйoe
оранжевыйyw
жёлтыйgn
зелёныйbe
синий, по умолчаниюpe
фиолетовыйpk
розовыйgy
серыйbk
чёрный
size
размер маркераs
маленький, по умолчаниюl
большой
Пример
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [ 82.89827, 55.03687 ]
},
"properties": {
"k": "c",
"c": "gn",
"s": "l"
}
}
Numbered Point & MultiPoint
Поддерживается стилизация номера и вида нумерованного маркера.
Properties
{
"k": "{kind}",
"n": {number}
}
number
номер от 1 до 99kind
вид маркераp
пин, по умолчаниюc
круг
Пример
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [ 82.89827, 55.03687 ]
},
"properties": {
"k": "c",
"n": 1
}
}
Custom Point & MultiPoint by URL
Поддерживаются адрес и точка привязки своего маркера.
Properties
{
"u": "{url}",
"a": "{x},{y}"
}
url
адрес картинкиx
точка привязки по горизонтали от левого верхнего угла, в диапазоне от 0 до 1 является относительным значением от ширины, больше 1 - абсолютное значение в пикселях, по умолчанию 0.5 (центр)y
точка привязки по вертикали от левого верхнего угла, в диапазоне от 0 до 1 является относительным значением от высоты, больше 1 - абсолютное значение в пикселях, по умолчанию 0.5 (центр)
Пример
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [ 82.89827, 55.03687 ]
},
"properties": {
"u": "https://example.org/img.png",
"a": "0.5,1"
}
}
Custom Point & MultiPoint by base64
Поддерживаются base64 значение и точка привязки своего маркера.
Properties
{
"b": "{base64}",
"a": "{x},{y}"
}
base64
картинка в стандартной кодировке base64x
точка привязки по горизонтали от левого верхнего угла, в диапазоне от 0 до 1 является относительным значением от ширины, больше 1 - абсолютное значение в пикселях, по умолчанию 0.5 (центр)y
точка привязки по вертикали от левого верхнего угла, в диапазоне от 0 до 1 является относительным значением от высоты, больше 1 - абсолютное значение в пикселях, по умолчанию 0.5 (центр)
Пример
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [ 82.89827, 55.03687 ]
},
"properties": {
"b": "base64string",
"a": "0.5,1"
}
}
LineString & MultiLineString
Поддерживается стилизация толщины и цвета линии.
Properties
{
"w": {weight},
"c": "{color}"
}
weight
толщина линии в пикселяхcolor
цвет линии
Пример
{
"type": "Feature",
"geometry": {
"type": "LineString",
"coordinates": [
[ 82.89827, 55.03687 ],
[ 82.90021, 55.03489 ],
[ 82.91062, 55.03264 ]
]
},
"properties": {
"w": 3,
"c": "03ee10"
}
}
Polygon & MultiPolygon
Поддерживается стилизация толщины и цвета контура, цвета заливки.
Properties
{
"w": {weight},
"c": "{color}",
"f": "{fill}"
}
weight
толщина контура в пикселяхcolor
цвет контураfill
цвет заливки
Пример
{
"type": "Feature",
"geometry": {
"type": "Polygon",
"coordinates": [[
[ 82.89827, 55.03687 ],
[ 82.90021, 55.03489 ],
[ 82.91062, 55.03264 ],
[ 82.91355, 55.03636 ],
[ 82.90925, 55.04067 ],
[ 82.89827, 55.03687 ]
]]
},
"properties": {
"w": 3,
"c": "03ee10",
"f": "03ee10a0"
}
}
GeometryCollection
Стилизация GeometryCollection не поддерживается потому как коллекция может содержать разные типы геометрий. Вместо этого используйте мультитипы либо отдельные Feature.
Тем не менее рендер объектов GeometryCollection из Feature будет работать, но в этом мало смысла, поэтому по возможности стоит использовать GeometryCollection напрямую либо FeatureCollection.
FeatureCollection
RFC 7946, Section 3.3, FeatureCollection Object
FeatureCollection позволяет объединить несколько Feature, К.О.
Пример
{
"type": "FeatureCollection",
"features": [{
"type": "Feature",
"geometry": {
"type": "LineString",
"coordinates": [
[ 82.91871, 55.03652 ],
[ 82.92131, 55.02711 ],
[ 82.92698, 55.02470 ]
]
},
"properties": {
"w": 5
}
}, {
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [ 82.92698, 55.02470 ]
},
"properties": {
"k": "c",
"n": 1
}
}, {
"type": "Feature",
"geometry": {
"type": "Polygon",
"coordinates": [[
[ 82.89827, 55.03687 ],
[ 82.90021, 55.03489 ],
[ 82.91062, 55.03264 ],
[ 82.91355, 55.03636 ],
[ 82.90925, 55.04067 ],
[ 82.89827, 55.03687 ]
]]
},
"properties": {
"c": "03ee10",
"f": "03ee10a0"
}
}]
}