Static API reference | 2GIS Documentation

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.

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

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

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 (RFC 7946).

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

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

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

На карте можно отобразить любые объекты по спецификации GeoJSON (RFC 7946) и стилизовать их в полях properties аналогично параметрам в URL.

Объекты передаются в параметре g и их необходимо закодировать для передачи в URL.

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 ]
        ]
    }]
}

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.

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"
        }
    }]
}