ORBISMap REST API v2.0

ORBISMap REST API позволяет взаимодействовать с картами, слоями и объектами внутри ORBISMap. Вы можете использовать ORBISMap REST API для создания, изменения или удаления карт, слоёв и объектов или для построения выборок данных опубликованных карт для того, чтобы использовать их на Вашем web-сайте или в Вашем приложении.

Доступные функции

Описание параметров

Описание параметров функций API, участвующих в URL запроса

Сервер принимает GET,POST,PUT,PATCH,DELETE запросы. Обратиться можно только к карте, для которой включена публикация. С учётом прав доступа и активной сессии. Все функции редактирования данных в обязательном порядке требуют предварительной авторизации.

Код каталога (project) выводится в верхней панели в строке навигации первым элементом. На рисунке ниже project="oms_tests_docker"

Описание дополнительных необязательных параметров всех функций API


Аутентификация

Аутентификация на проекте

POST http://<host>/api/2.0/<project_code>/login/

Здесь и далее считается, что за авторизованную сессию отвечает только параметр token. Он выдается как результат функции аутентификации и является идентификатором сессии. Сессия хранится на сервере в течении одного месяца после последнего запроса с ее участием, после чего автоматически уничтожается. Идентификатор сессии необходим при выполнении любых операций создания/изменения/удаления с использованием REST API. Для этого идентификатор сессии нужно передать в параметре token запроса. Результат выполнения любых операций REST API (как получения, так и изменения) зависит от настроек прав доступа пользователей в ORBISMap. Если token не передан в функцию, результат будет зависеть от настроек прав доступа публичного пользователя, иначе - от настроек прав доступа пользователя, определяемого переданным token.

Обязательные параметры запроса:

Ответ

{
    "token": "Токен авторизации"
}

Завершить авторизованную сессию

POST http://<host>/api/2.0/<project_code>/logout/

Обязательные параметры запроса:

Ответ

{
    "token": ""
}

Работа с картой

Получить объект карты

GET http://<host>/api/2.0/<project_code>/<map_code>/

Здесь и далее считается, что в случае, если карта не опубликована и пользователь не авторизовался, система вернет ошибку доступа со статусом 403.

Ответ

{
    "id": 1,
    "code": "map1",
    "name": "Карта 1",
    "css_style": "CartoCSS-стиль отображения карты - подложка для рисования слоев",
    "group_layers": 0,
    "has_publication": true
}

Создать карту

POST http://<host>/api/2.0/<project_code>/

Обязательные параметры запроса:

{
    "code": "new_map",
    "name": "Новая карта",
    "css_style": "CartoCSS-стиль отображения карты - подложка для рисования слоев",
    "publish": True
}

Где:

- `code` - код создаваемой карты
- `name` - имя карты
- `css_style` - CartoCSS-стиль отображения карты, *необязательный параметр* (в случае отсутствия значения будет использован стиль отображения по умолчанию)
- `publish` - опубликовать карту, *необязательный параметр*

Ответ

{
    "id": 22,
    "code": "new_map",
    "name": "Новая карта",
    "css_style": "CartoCSS-стиль отображения карты - подложка для рисования слоев",
    "group_layers": 1 
}

Получить дерево слоев

GET http://<host>/api/2.0/<project_code>/<map_code>/layers/

Необязательные параметры запроса:

Ответ

[
    {
        "id": 1,
        "type": "layer",
        "code": "layer1",
        "name": "Слой 1",
        "sort": 1,
        "bbox": {
            "sw" : [Lat, Lon],
            "ne" : [Lat, Lon]
        },
        "parent_id": 0,
        "selected": false,
        "map_layer_id": 1,
        "icon": "static/path/icon.png",
        "icon_retina": "static/path/icon.png",
        "g_type": "Point|LineString|Polygon|Unknown",
        "render_type": 0,
    },
    {
        "id": 2,
        "sort": 2,
        "parent_id": 0,
        "code": "layer2",
        "name": "Слой 2",
        "type": "layer",
        "selected": true,
        "render_type": 0,
        "...": "..."
    },
    {
        "id": 3,
        "sort": 3,
        "parent_id": 0,
        "map_layer_id": 3,
        "code": "layer3",
        "name": "Слой 3",
        "render_type": 0,
        "...": "..."
    },
    {
        "id": 4,
        "sort": 4,
        "parent_id": 0,
        "code": "folder1",
        "name": "Папка 1",
        "type": "folder",
        "render_type": 0,
        "...": "..."
    },
    {
        "id": 5,
        "sort": 1,
        "parent_id": 4,
        "code": "layer4",
        "name": "Слой 4 в Папке 1",
        "type": "layer",
        "render_type": 0,
        "...": "..."
    },
    {
        "id": 6,
        "sort": 2,
        "parent_id": 4,
        "code": "vector_layer",
        "name": "Векторный слой в Папке 1",
        "type": "layer",
        "render_type": 1,
        "vectorSettings": {
            "...": "...",
        },
        "...": "..."
    },
    {
        "id": 7,
        "sort": 3,
        "parent_id": 4,
        "code": "visualisation",
        "name": "Визуализация слой в Папке 1",
        "type": "visual",
        "render_type": 0,
        "visualSettings": {
            "...": "...",
        },
        "...": "..."
    }
]

Где

vectorSettings

{
    "vectorSettings": {
        "stylesPolygon": {},
        "stylesText": {},
        "minZoom": 2,
        "clusterSettings": {
            "objectsCountDx": 0,
            "icon": null,
            "showObjectsCount": true,
            "iconSizeMax": 25,
            "radius": 40,
            "iconSizeEnabled": false,
            "iconDx": 0,
            "iconEnabled": false,
            "iconOffsetEnabled": false,
            "iconDy": 0,
            "iconSizeMin": 15,
            "clusteringType": "client",
            "objectsCountDy": 0,
            "maxZoom": 12,
            "maxZoomEnabled": false,
            "splitByCategories": false
        },
        "popupColumn": 1065,
        "maxZoom": 5,
        "popupColumnCode": "orbis_id",
        "showPopup": false,
        "code": "entity",
        "zoomsEnabled": false,
        "clusteringEnabled": true,
        "id": 21,
        "stylesPoint": {
            "icon": null,
            "iconDx": 0,
            "iconOffsetEnabled": true,
            "iconDy": 0
        },
        "stylesLine": {}
    }
}

visualSettings

{
    "visualSettings": {
        "algorithm": 1,
        "showLegend": false,
        "showText": false,
        "pointSettings": {
            "size": 10.0,
            "allowOverlap": true,
            "sizeEnabled": false
        },
        "borderSettings": {
            "opacity": 100,
            "pattern": 1,
            "width": 1.0,
            "color": "#FFFFFF"
        },
        "column": 1071,
        "columnCode": "type",
        "classesSettings": {
            "opacity": 80,
            "defaultClass": null,
            "linePattern": 1,
            "lineWidth": 1.0,
            "classes": [{
                "value": "Область",
                "checked": true,
                "color": "#80f320",
                "count": 46,
                "icon": "\/img\/db_lmv\/aa.png",
                "useIcon": false
            }, {
                "value": "Республика",
                "checked": true,
                "color": "#d3b501",
                "count": 22,
                "icon": "\/img\/db_lmv\/p.png",
                "useIcon": false
            }, {
                "value": "Край",
                "checked": false,
                "color": "#fe5c20",
                "count": 9,
                "icon": null,
                "useIcon": false
            }, {
                "value": "Автономный округ",
                "checked": false,
                "color": "#eb156e",
                "count": 4,
                "icon": null,
                "useIcon": false
            }, {
                "value": "Город федерального",
                "checked": false,
                "color": "#a402c5",
                "count": 2,
                "icon": null,
                "useIcon": false
            }, {
                "value": "Автономная область",
                "checked": false,
                "color": "#4b2dfa",
                "count": 1,
                "icon": null,
                "useIcon": false
            }, {
                "value": "Город федерального значения",
                "checked": false,
                "color": "#0c80f3",
                "count": 1,
                "icon": null,
                "useIcon": false
            }]
        },
        "classesCount": 9,
        "code": "entity",
        "legendName": "",
        "showBorder": true,
        "showValues": false,
        "id": 16,
        "textSettings": {
            "offsetEnabled": false,
            "haloWidth": 1.0,
            "textOffset": 10.0,
            "halo": true,
            "haloOpacity": 100,
            "column": "orbis_id",
            "fontFamily": "Arial Bold",
            "fontSize": 12.0,
            "fontColor": "#000000",
            "fontOpacity": 100,
            "allowOverlap": false,
            "haloColor": "#ffffff"
        },
        "type": 2,
        "legendNames": [{
            "ru": ""
        }],
        "showLegendName": false
}

Сохранить дерево публикации

POST http://<host>/api/2.0/<project_code>/<map_code>/publish/

Формат запроса:

[
    {
        "id": 1,
        "sort": 1,
        "parent_id": 0,
        "selected": true,
        "map_layer_id": 1,
        "icon": "static/path/icon.png",
        "icon_retina": "static/path/icon.png",
    },
    {
        "id": 2,
        "sort": 1,
        "parent_id": 1,
        "selected": true,
        "map_layer_id": 2,
        "icon": "static/path/icon.png",
        "icon_retina": "static/path/icon.png",
    },
    {
        "id": 3,
        "sort": 2,
        "parent_id": 1,
        "selected": true,
        "map_layer_id": 3,
        "icon": "static/path/icon.png",
        "icon_retina": "static/path/icon.png",
    },
    ...
]

Где:

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

Ответ

Формат ответа совпадает с функцией Получить дерево слоев с параметрами по умолчанию.

Получение начальных настроек публичной карты.

GET http://<host>/api/2.0/<project_code>/

Формат запроса:

{
    "map_code": "new_map",
}

Полученный файл конфигурации инициализирует первоначальную работу ORBISMap JS API


Работа со слоями

Получить слой карты

GET http://<host>/api/2.0/<project_code>/<map_code>/layers/<layer_code>/

Ответ

{
    "id": 1,
    "type": "layer",
    "code": "layer1",
    "name": "Слой 1",
    "sort": 1,
    "bbox": {
        "sw" : ["Lat", "Lon"],
        "ne" : ["Lat", "Lon"]
    },
    "parent_id": 0,
    "selected": false,
    "map_layer_id": 1,
    "icon": "static/path/icon.png",
    "icon_retina": "static/path/icon.png",
    "g_type": "Point|LineString|Polygon|Unknown",
    "css_style": "CartoCSS-стиль отображения слоя",
    "render_type": 0
}

Получить легенду слоя карты

GET http://<host>/api/2.0/<project_code>/<map_code>/layers/<layer_code>/legend/

Ответ

{
    "name": "Название легенды",
    "showValues": true,
    "classificators": [
        {
            "value": "orbis_id",
            "fill":"#f82851",
            "isIcon": false
        }
    ],
    "showLegend": true,
    "column": "orbis_id",
    "type": 5,
    "minValue": 1,
    "maxValue": 200
}

Создать слой

POST http://<host>/api/2.0/<project_code>/<map_code>/layers/

Обязательные параметры запроса:

{
    "code": "new_layer",
    "localized_name": true,
    "name": "Имя",
    "parent_id": 2,
    "sort": 3.5,
    "css_style": "CartoCSS-стиль отображения слоя"
}

Где:

- `code` - код создаваемого слоя
- `localized_name` - флаг, локализовать ли название слоя, *необязательный параметр (по умолчанию false)*
- `name` - имя слоя для локализации с кодом = `значение параметра <lng>` (либо, если не параметр lng не задан, для локализации по умолчанию) *необязательный параметр* 
- `parent_id` - идентификатор родительского контейнера (`карта/папка`), в котором будет находиться слой в дереве, *необязательный параметр (по умолчанию слой будет создаваться непостредственно в указанной карте)*
- `sort` - значение сортировки для создаваемого слоя (при изменении сортировки сервер выполнит пересортировку всех элементов в пределах указанного `parent_id`, в результате чего значение сортировки для каждого контейнера будет целочисленным), *необязательный параметр (по умолчанию слой будет добавлять последним для указанного `parent_id`)*
- `css_style` - CartoCSS-стиль отображения слоя, *необязательный параметр* (в случае отсутствия значения будет использован стиль отображения по умолчанию)

Ответ

{
    "id": 9,
    "code": "new_layer",
    "name": "Новый слой",
    "parent_id": 2,
    "css_style": "CartoCSS-стиль отображения слоя",
    "type": "layer",
    "selected": "false",
    "icon": "static/path/icon.png",
    "icon_retina": "static/path/icon.png",
    "g_type": "Point|LineString|Polygon|Unknown",
    "sort": 4,
    "bbox": {
        "sw" : [Lat, Lon],
        "ne" : [Lat, Lon]
    },
    "render_type": 0
}

Изменить слой

PUT http://<host>/api/2.0/<project_code>/<map_code>/layers/<layer_code>/

Необходимо передавать все значения.

Обязательные параметры запроса:

{
    "code": "new_layer_1",
    "localized_name": true,
    "name": "Новое Имя",
    "parent_id": 3,
    "sort": 1.5,
    "css_style": "CartoCSS-стиль отображения слоя",
    "...": "..."
}

Ответ

{
    "id": 9,
    "code": "new_layer_1",
    "name": "Новое Имя",
    "parent_id": 3,
    "css_style": "CartoCSS-стиль отображения слоя",
    "type": "layer",
    "selected": "false",
    "icon": "static/path/icon.png",
    "g_type": "Point|LineString|Polygon|Unknown",
    "sort": 2,
    "bbox": {
        "sw" : [Lat, Lon],
        "ne" : [Lat, Lon]
    }
}

Работа со структурой слоя

Получить структуру слоя

GET http://<host>/api/2.0/<project_code>/<map_code>/layers/<layer_code>/structure/

Ответ

[
    {
        "id":48,
        "sort":1,
        "parent_id":0,
        "code":"orbis_id",
        "name":"",
        "required": true,
        "type":"number",
        "localized_name":false,
        "localized_value":false
    },
    {
        "id":49,
        "sort":2,
        "parent_id":0,
        "code":"geom",
        "name":"",
        "required": false,
        "type":"geom",
        "localized_name":false,
        "localized_value":false
    },
    {
        "id":50,
        "sort":3,
        "parent_id":0,
        "code":"titles",
        "name":"Подписи",
        "type":"title",
        "localized_name":true,
        "localized_value":false
    },
    {
        "id":51,
        "sort":1,
        "parent_id":50,
        "code":"label_en",
        "name":"Подпись английская",
        "required": true,
        "type":"title|number|string|text|datetime|bool|file|geom",
        "localized_name":true,
        "localized_value":false
    },
    {
        "id":52,
        "sort":2,
        "parent_id":50,
        "code":"label_ru",
        "name":"Подпись русская",
        "required": false,
        "type":"title|number|string|text|datetime|bool|file|geom",
        "localized_name":true,
        "localized_value":false
    }
]

Изменить колонку

PUT http://<host>/api/2.0/<project_code>/<map_code>/layers/<layer_code>/structure/<field_code>/

Необходимо передавать все значения.

Обязательные параметры запроса:

{
    "code": "New_column_1",
    "name": "Новая колонка 1",
    "localized_name": true,
    "localized_value": false,
    "required": false,
    "type": "number",
    "sort":4.5,
    "parent_id": 50,
    "...": "..."
}

Ответ

{
    "id":53,
    "sort":3,
    "parent_id":50,
    "code":"New_column_1",
    "name":"Новая колонка 1",
    "required": false,
    "type":"number",
    "localized_name":true,
    "localized_value":false
}

Работа с данными слоя

Загрузка данных в слой

POST http://<host>/api/2.0/<project_code>/<map_code>/layers/<layer_code>/import/

Загрузка данных поддерживает следующие форматы:

Вектор:

Растр:

Возможные способы загрузки:

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

либо

Дополнительные необязательные параметры:

Ответ

{
    "id": 8,
    "code": "layer1",
    "name": "Слой 1",
    "parent_id": 2,
    "css_style": "CartoCSS-стиль отображения слоя",
    "type": "layer",
    "selected": false,
    "icon": "static/path/icon.png",
    "icon_retina": "static/path/icon.png",
    "g_type": "Point|LineString|Polygon|Unknown",
    "sort": 6,
    "bbox": {
        "sw" : [Lat, Lon],
        "ne" : [Lat, Lon]
    }
}

Выгрузка данных слоя

GET http://<host>/api/2.0/<project_code>/<map_code>/layers/<layer_code>/export/

Выгрузка данных поддерживает следующие форматы:

Вектор:

Растр:

Обязательные GET-параметры:

Необязательные дополнительные GET-параметры:

Дополнительные GET-параметры для экспорта CSV

Ответ zip-архив (для типов shp,mif) или файл (для типов geojson, kml, kmz, xls, csv) с результатом. Если указан параметр zip, то файлы любого типа (кроме kmz) будут сжаты в *.zip. Экспорт в kmz всегда возвращает файл *.kmz, вне зависимости от наличия параметра сжатия.


Работа с объектами слоя

Получить список объектов слоя

GET http://<host>/api/2.0/<project_code>/<map_code>/layers/<layer_code>/objects/

Необязательные параметры запроса:

Ответ

[
    {
        "id": "2", 
        "fields": {
                "field_1": "Значение колонки 1 объекта 2",
                "field_2": 456.123
        },
        "geom": { 
            "type": "Polygon", 
            "coordinates": [ 
                [ 
                    [ 39.674470691019003, 45.201854294024443 ], 
                    [ 39.672229085150633, 45.164807545385699 ], 
                    [ 39.728412719962421, 45.151394461232584 ],  
                    [ 39.674470691019003, 45.201854294024443 ] 
                ] 
            ] 
        },
        "bbox": {
            "sw" : [39.67222, 45.20185],
            "ne" : [39.72841, 45.15139]
        }
    }
]

Получить информацию по объекту слоя

GET http://<host>/api/2.0/<project_code>/<map_code>/layers/<layer_code>/objects/<object_id>/

Необязательные параметры запроса:

Ответ

{
    "id": 1,
    "fields": {
        "field_1": "Значение колонки 1",
        "field_2": "Значение колонки 2",
        "field_3": 3
    },
    "geom": { 
        "type": "Polygon", 
        "coordinates": [ 
            [ 
                [ 39.674470691019003, 45.201854294024443 ], 
                [ 39.672229085150633, 45.164807545385699 ], 
                [ 39.728412719962421, 45.151394461232584 ],  
                [ 39.674470691019003, 45.201854294024443 ] 
            ] 
        ] 
    },
    "bbox": {
        "sw" : [39.67222, 45.20185],
        "ne" : [39.72841, 45.15139]
    }
}

Получить информацию по геометрии объекта слоя

GET http://<host>/api/2.0/<project_code>/<map_code>/layers/<layer_code>/objects/<object_id>/geom/

Обязательные параметры запроса:

Ответ

{ 
    "type": "Point",
    "coordinates": [ 3673543.19617802882567, 3895303.963393894489855 ] 
}

Изменить информацию по геометрии объекта слоя

PUT/PATCH http://<host>/api/2.0/<project_code>/<map_code>/layers/<layer_code>/objects/<object_id>/geom/

Если используется PUT, то необходимо передавать все значения. Если используется PATCH, то можно передавать только те значения, которые требуют изменения.

Обязательные параметры запроса:

Необязательные параметры запроса:

{
    "geom": {
        "coordinates": [61.33891, 35.83611],
        "type": "Point"
   }
}

Ответ

{
    "geom": {
        "coordinates": [6828216.22701, 4278093.73065],
        "type": "Point"
    }
}

Работа с файлами

Добавить файл к объекту

POST http://<host>/api/2.0/<project_code>/<map_code>/layers/<layer_code>/objects/<object_id>/files/

Обязательные параметры запроса

Ответ

{
    "name": "имя загруженного файла.m4a", 
    "path": "//<host>/static/content_files/oms_tests_docker/0bb97e774aee56cf3e7b0b0717ab62ce.m4a", 
    "mime": "audio/x-m4a", 
    "id": 3, 
    "code": "",
    "uuid": "754279f7-fdf1-4f75-a5d8-1bbd18c3dd5b"
}

Удалить файл объекта

DELETE http://<host>/api/2.0/<project_code>/<map_code>/layers/<layer_code>/objects/<object_id>/files/<file_id>/

Обязательные параметры запроса

Ответ

null

Запрос изображений

Позволяет на лету изменить размер любого изображения, привязанного к любому объекту в системе. Например создать уменьшенную копию изображения.

GET http://<host>/api/2.0/<project_code>/image/<file_uuid>/

Необязательные параметры запроса:


Обработка ошибок

HTTP-статусы выполнения запросов:

{
    "error": "error|warning|notice",
    "code": "код_ошибки",
    "message": "Описание ошибки выполнения запроса",
    "data": {}
}

Где: - data - всегда json-объект, который может содержать дополнительную информацию по ошибке. Например, список обязательных параметров запроса или колонок, установление значения для которых вызывало ошибку при редактировании объекта.


Версии API