Справочник API | Static API | 2GIS Documentation

Справочник 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).

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

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

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

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

Значения:

  • 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
    

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

Линия

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
    

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

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

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

Маркер (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.

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