Справочник API Static API

Текущая версия API: 1.0.

Точка входа: static.maps.2gis.com.

Все параметры передаются через query. Общий вид запроса:

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

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

Общая информация

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

Координаты

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

Знак плюс + для положительных координат можно не указывать. Если вы используете плюс +, закодируйте его для передачи в URL: %2B.

Цвета

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

Префиксы # или 0x для цветов можно не указывать. Если вы используете префикс #, закодируйте его для передачи в URL: %23.

Карта

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

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

Размер

Обязательный параметр.

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

Задаёт размер карты в пикселях и модификатор размера для различных экранов.

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

Значения:

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

Примеры:

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

Центр

Обязательный параметр, если на карте нет дополнительных объектов.

c={lat},{lon}

Задаёт координаты центра карты.

Значения:

lat - широта в градусах;
lon - долгота в градусах.

Примеры:

Координаты Третьяковской галереи:
```
c=55.7414,37.6209
```

Масштаб

Обязательный параметр, если на карте нет дополнительных объектов.

z={zoom}

Задаёт масштаб карты.

Значения:

zoom - масштаб карты, от 1 до 18.

Примеры:

Двойное увеличение:
```
z=2
```
Десятикратное увеличение:
```
z=10
```

Объекты

На карту можно добавить маркеры, линии и многоугольники в различных стилях. Формат описания во многом схож с GeoJSON (RFC 7946).

Маркеры (Point & MultiPoint)

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

Обычный маркер

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

Параметр задаёт координаты, форму, цвет и размер маркера.

Значения:

lat - широта в градусах;
lon - долгота в градусах;
kind - форма маркера:
- p - пин (по умолчанию),
- c - круг.
color - цвет маркера:
- be - синий (по умолчанию),
- rd - красный,
- oe - оранжевый,
- yw - жёлтый,
- gn - зелёный,
- 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
```

Нумерованный маркер

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

Параметр задаёт координаты, номер и форму нумерованного маркера.

Значения:

lat - широта в градусах;
lon - долгота в градусах;
number - номер маркера, от 1 до 99;
kind - форма маркера:
- p - пин (по умолчанию),
- c - круг.

Примеры:

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

Кастомный маркер (URL)

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

Параметр задаёт координаты, адрес изображения и точку привязки для кастомного маркера.

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

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

Значения:

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

Примеры:

Кастомный маркер с привязкой по центру:
```
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
```
Кастомный маркер с привязкой в точке 12,16 пикселей:
```
pt=55.7368,37.6326~u:http://example.com/image.png~a:12,16
```

Кастомный маркер (Base64)

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

Параметр задаёт координаты, изображение в формате Base64 и точку привязки для кастомного маркера.

Значения:

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

Примеры:

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

Множество маркеров

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

Настройки стиля можно применить сразу к нескольким маркерам.

Примеры:

Три маленьких синих пина (по умолчанию):
```
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

Два кастомных маркера (URL):

pt=55.7368,37.6326~55.7468,37.6226~u:http%3A%2F%2Fexample.com%2Fimage.png

Два кастомных маркера (Base64):

pt=55.7368,37.6326~55.7468,37.6226~b:base64string

Линии (LineString & MultiLineString)

На карту можно добавить ломаные линии с заданными цветом и толщиной.

Линия

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

Параметр задаёт координаты вершин ломаной линии, её толщину и цвет.

Значения:

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

Примеры:

Синяя линия (по умолчанию):
```
ls=55.736,37.632,55.746,37.632
```
Линия толщиной в 7 пикселей:
```
ls=55.736,37.632,55.746,37.632~w:7
```

Красная линия:

ls=55.736,37.632,55.746,37.632~c:ff0000

Зелёная линия толщиной в 6 пикселей:
```
ls=55.736,37.632,55.746,37.632~w:6~c:00ff00
```

Множество линий

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

Настройки стиля можно применить сразу к нескольким линиям.

Примеры:

Две синих линии (по умолчанию):

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&ls=55.836,37.632,55.846,37.632

Две зелёных линии толщиной в 6 пикселей:

ls=55.736,37.632,55.746,37.632~55.836,37.632,55.846,37.632~w:6~c:00ff00

Многоугольники (Polygon & MultiPolygon)

На карту можно добавить многоугольники (без вырезов) с заданными цветом и толщиной контура, а также цветом заливки.

Многоугольник

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
```
Многоугольник с толщиной контура в 7 пикселей:
```
pn=55.736,37.632,55.746,37.632,55.746,37.642~w: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
```
Многоугольник с зелёным контуром толщиной в 6 пикселей и жёлтой полупрозрачной заливкой:
```
pn=55.736,37.632,55.746,37.632,55.746,37.642~w:6~c:00ff00~f:ffff00aa
```

Множество многоугольников

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

Настройки стиля можно применить сразу к нескольким многоугольникам.

Примеры:

Два синих многоугольника с полупрозрачной заливкой (по умолчанию):
```
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

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

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 позволяют настраивать стили геометрий.

Маркер (Point & MultiPoint)

Для стандартного маркера можно задать форму, цвет и размер.

Properties:

{
    "k": "{kind}",
    "c": "{color}",
    "s": "{size}"
}

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

Пример:

{
    "type": "Feature",
    "geometry": {
        "type": "Point",
        "coordinates": [ 82.89827, 55.03687 ]
    },
    "properties": {
        "k": "c",
        "c": "gn",
        "s": "l"
    }
}

Нумерованный маркер

Для нумерованного маркера можно задать форму и номер.

Properties:

{
    "k": "{kind}",
    "n": {number}
}

kind - форма маркера:
- p - пин (по умолчанию),
- c - круг.
number - номер маркера, от 1 до 99.

Пример:

{
    "type": "Feature",
    "geometry": {
        "type": "Point",
        "coordinates": [ 82.89827, 55.03687 ]
    },
    "properties": {
        "k": "c",
        "n": 1
    }
}

Кастомный маркер (URL)

Для кастомного маркера можно задать адрес и точку привязки.

Properties:

{
    "u": "{url}",
    "a": "{x},{y}"
}

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

Пример:

{
    "type": "Feature",
    "geometry": {
        "type": "Point",
        "coordinates": [ 82.89827, 55.03687 ]
    },
    "properties": {
        "u": "https://example.org/img.png",
        "a": "0.5,1"
    }
}

Кастомный маркер (Base64)

Для кастомного маркера можно задать изображение в формате Base64 и точку привязки.

Properties:

{
    "b": "{base64}",
    "a": "{x},{y}"
}

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

Пример:

{
    "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 будет работать, но задать стили для них нельзя, так как коллекция может содержать разные типы геометрий. Вместо этого используйте отдельные объекты Feature или их коллекцию - 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"
        }
    }]
}