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

Значения

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

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 до 99
kind вид маркера
- 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 картинка в стандартной кодировке base64
x точка привязки по горизонтали от левого верхнего угла, в диапазоне от 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"
        }
    }]
}