REST API, версия 1

Использование REST API ГеоМиксер

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

Для выполнения операций и контроля доступа все запросы должны быть аутентичны.
Для этого пользователь должен добавить в качестве параметра запроса свой прямой API-ключ,
который можно получить на my.kosmosnimki.ru.
Необходимо войти под зарегистрированной учетной записью и открыть вкладку
API-ключи. Там необходимо нажать на ссылку Получение
API-ключа прямого доступа (для приложений)
. После активации ключ
появится в поле Ключ прямого доступа.

Осуществление вызовов

Вызовы осуществляются посредством HTTP/HTTPS-запросов, п

ри этом предпочтительнее использовать HTTPS.
В качестве методов могут быть использованы POST и GET – различий между ними на данный момент нет.
Методы PUT и DELETE не поддерживаются. Параметры могут быть переданы как в URL, так и в теле POST-запроса.
Названия параметров не зависят от регистра. Результат выполнения операции содержится в коде состояния HTTP.
Перечень возможных кодов приведен в таблице ниже. Если результат содержит данные, то они возвращаются в теле ответа,
как правило, в формате JSON. Для некоторых типов запросов поддерживаются несколько форматов ответа.
Если результат содержит ошибку, то в теле возвращается JSON-объект со свойствами:

Свойство Тип Описание
error Строка Сообщение о некорректной работе

Коды результатов ответа

В REST API используются следующие коды HTTP в качестве результатов:

Код результата Когда используется
200 OK Возвращается в случае успешно выполненной операции, тело, как правило, содержит дополнительную информацию.
400 Bad Request Возвращается в случае, если в запросе содержится ошибка, например, неправильно задан один из параметров.
403 Forbidden Возвращается в случае неавторизованного доступа (когда для доступа необходим API-ключ, но он не указан либо указан неправильный ключ).
404 Not Found Возвращается в случае, если не найден какой-либо объект, участвующий в запросе, например, слой.
500 Internal Server Error Возвращается в случае ошибки, произошедшей при работе сервера.
501 Not Implemented Возвращается в случае, если запрошенная операция не реализована.

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

Далее везде layer_id обозначает 16-ти символьный идентификатор слоя. Параметры, помечаемые символом “*”, являются обязательными.

Создание слоя

URL: /rest/ver1/layers/create

Параметры запроса:

Параметр Тип Описание
api_key * Строка API-ключ пользователя
type * Строка Тип создаваемого слоя. Возможные значения: raster,
vector.
Если указано некорректное значение, то будет возвращена ошибка. Для каждого типа слоя
необходимо использовать свой набор параметров.
title * Строка Название слоя
timeout Целое Время ожидания выполнения операции в миллисекундах. Значение не может превышать 60000, т.е. одной минуты.
Если параметр не указан или имеет неположительное значение, то операция выполняется асинхронно -
ответ содержит идентификатор задачи, по которому необходимо отслеживать процесс выполнения задачи. Такой же ответ
будет возвращен пользователю, если операция выполняется более указанного таймаута.
Если задача была успешно выполнена за отведенное время, то будет возвращен идентификатор созданного слоя.

Дополнительные параметры запроса создания растрового слоя:

Параметр Тип Описание
TilePath * Строка Путь к растровому файлу-контейнеру в директории пользователя на сервере
BorderFile Строка Путь к файлу границы в директории пользователя на сервере
BorderGeometry Строка Геометрия границы слоя в формате GeoJson
Description Строка Описание слоя

Дополнительные параметры запроса создания векторного слоя:

Параметр Тип Описание
Columns Массив JSON-объектов Массив объектов, описывающих колонки создаваемого слоя. Объекты должны содержать
два свойства: строковое Name – название колонки и строковое ColumnSimpleType –
тип колонки, возможные значения: Integer, Float, String, Date, DateTime, Time,
Boolean
GeometryType Строка Тип геометрии, возможные значения: Point, LineString, Polygon

Данные в ответе: если слой был успешно создан, то результатом является JSON-объект со свойством:

Свойство Тип Описание
id Строка Идентификатор созданного слоя

если операция не была выполнена за отведенный таймаут или возникла ошибка
асинхроной операции, то результатом является JSON-объект со свойствами:

Свойство Тип Описание
task Строка Идентификатор выполняемой операции, который необходимо использовать для
отслеживания результата операции
completed Строка Состояние операции. Может иметь значение true (выполнено, но с ошибками) и false
(не выполнено, требуется отслеживание результата, поле error при этом пустое)
error JSON-объект Ошибка выполнения асинхронной операции

Пример: создание векторного слоя с двумя колонками –
целочисленным id и строковым path:


http://maps.kosmosnimki.ru/rest/ver1/layers/create?type=vector&title=NewLayer&Columns=[{%22Name%22:%22id%22,%22ColumnSimpleType%22:%22Integer%22},{%22Name%22:%22path%22,%22ColumnSimpleType%22:%22String%22}]&api_key=API_KEY

Удаление слоя

URL: /rest/ver1/layers/delete

Параметры запроса:

Параметр Тип Описание
api_key * Строка API-ключ пользователя
id * Строка Идентификатор слоя

Данные в ответе: если операция выполнена успешно, то результат
пустой.

Пример: удаление слоя:


https://maps.kosmosnimki.ru/rest/ver1/layers/delete?id=55416EE4B50D42269F267D650A890151&api_key=API_KEY

Поиск объектов векторного слоя

URL: /rest/ver1/layers/layer_id/search[.format]

format – формат результата, может отсутствовать или быть одним из значений: geojson (по умолчанию), gmx (внутренний формат Geomixer Json).

Параметры запроса:

Параметр Тип Описание
api_key * Строка API-ключ пользователя
query Строка Фильтр поиска
columns Строка Названия столбцов атрибутов, включаемых в результат; указываются в двойных
кавычках через запятую
orderby Строка Название столбца для сортировки результата
orderdirection Строка Порядок сортировки; возможные значения: asc, desc
skiprecords Целое Количество пропускаемых объектов в результате
limitrecords Целое Максимальное количество объектов в результате; в любом случае сервер вернет не более 1000 объектов
out_cs Строка Формат выходной системы координат, возможные значения: EPSG:4326 (по умолчанию), EPSG:3395, EPSG:3857
border Строка Геометрия в формате GeoJson или WKT, ограничивающая область поиска
border_cs Строка Формат входной системы координат параметра border, возможные значения: EPSG:4326 (по умолчанию), EPSG:3395, EPSG:3857
count Строка Возможные значения: true/false (по умолчанию) определяют, что вернет запрос: только количество объектов в выборке (true) или же сами объекты (false)
BorderFromLayer Строка Идентификатор слоя, из которого берется геометрия, ограничивающая область поиска.
Это может быть растровый слой или векторный слой (в этом случае может присутствовать параметр BorderId)
BorderId Целое Идентификатор объекта векторного слоя, из которого будет взята геометрия, ограничивающая область поиска; используется вместе с BorderFromLayer

Данные в ответе: если операция выполнена успешно, то результат
будет зависеть от параметров запроса. Если параметр count имел значение true, то
результ – целое число. В противном случае будет возвращено множество объектов в
запрошенном формате. Для geojson будет возвращен FeatureCollection, а для gmx –
JSON-объект со свойствами:

Свойство Тип Описание
fields Массив строк Массив названий атрибутов слоя
types Массив строк Массив типов атрибутов слоя
values Двумерный массив Множество массивов значений атрибутов каждой записи слоя

Пример: запрос количества объектов в слое, имеющем поле ACQDATE за конкретную дату:



https://maps.kosmosnimki.ru/rest/ver1/layers/04DDB23F49F84B9A9122CBA6BC26D3ED/search?count=true&query=”ACQDATE”=’2014-10-25′&key=API_KEY

Пример: запрос объектов в слое, имеющем поле ACQDATE за конкретную дату,
пересекающихся с геометрией другого слоя:

https://maps.kosmosnimki.ru/rest/ver1/layers/7F558F0735A6488780AE8C6234327953/search?query=%5Bacqdate%5D+%3E%3D+%2701.01.2014%27+and+%5Bacqdate%5D+%3C%3D+%2701.12.2014%27&BorderFromLayer=13EF16E4ABAD44F1A2EA020E053AB56E&api_key=API_KEY


Создание объекта векторного слоя

URL: /rest/ver1/layers/layer_id/create

Параметры запроса:

Параметр Тип Описание
api_key * Строка API-ключ пользователя
feature * JSON-объект Создаваемый объект. Объект может иметь свойства geometry (в формате GeoJson) и properties (в формате JSON);
названия и типы атрибутов должны соответствовать атрибутам слоя.
Если соответсвующий атрибут отсутствует в слое, то он будет проигнорирован.
geometry_cs Строка Формат входной системы координат свойства geometry, возможные значения: EPSG:4326 (по умолчанию), EPSG:3395, EPSG:3857

Данные в ответе: результатом является JSON-объект со свойством:

Свойство Тип Описание
id Целое Идентификатор созданного объекта

Пример: создание новой записи в слое с геометрией и параметрами:



https://maps.kosmosnimki.ru/rest/ver1/layers/EB840C54020749339EF7688E3FBD7139/create?feature={“properties”:{“SceneID”:”AM1_2014_12_12″,”Sensor”:”TERRA”},”geometry”:{“type”:”Polygon”,”coordinates”:[[[36,51.5],[36,52],[34,52.5],[36,51.5]]]}}&api_key=API_KEY

Создание нескольких объектов векторного слоя

URL: /rest/ver1/layers/layer_id/create

Параметры запроса:

Параметр Тип Описание
api_key * Строка API-ключ пользователя
features * массив JSON-объектов Создаваемые объекты. Объекты могут иметь свойства geometry (в формате GeoJson) и properties (в формате JSON);
названия и типы атрибутов должны соответствовать атрибутам слоя.
Если соответсвующий атрибут отсутствует в слое, то он будет проигнорирован.
geometry_cs Строка Формат входной системы координат свойства geometry, возможные значения: EPSG:4326 (по умолчанию), EPSG:3395, EPSG:3857

Данные в ответе: результатом является JSON-объект со свойством:

Свойство Тип Описание
ids Массив целых Идентификаторы созданных записей

Пример: создание нескольких новых записей в слое с геометрией или параметрами:



https://maps.kosmosnimki.ru/rest/ver1/layers/EB840C54020749339EF7688E3FBD7139/create?features=[{"properties":{"SceneID":"AM1_2014_12_12","Sensor":"TERRA"}},{"geometry":{"type":"Polygon","coordinates":[[[36,51.5],[36,52],[34,52.5],[36,51.5]]]}}]&api_key=API_KEY

Изменение объекта векторного слоя

URL: /rest/ver1/layers/layer_id/update

Параметры запроса:

Параметр Тип Описание
api_key * Строка API-ключ пользователя
feature * JSON-объект Изменяемый объект. Объект должен иметь свойство id – целочисленный идентификатор изменяемой записи.
Объект может иметь свойства geometry (в формате GeoJson) и properties (в формате JSON);
названия и типы атрибутов должны соответствовать атрибутам слоя.
Если соответсвующий атрибут отсутствует в слое, то он будет проигнорирован.
geometry_cs Строка Формат входной системы координат свойства geometry, возможные значения: EPSG:4326 (по умолчанию), EPSG:3395, EPSG:3857

Данные в ответе: если операция выполнена успешно, то результат пустой. Если объект не был найден, то результатом является JSON-объект со свойствами:

Свойство Тип Описание
warning Строка Сообщение о некорректной работе
id Целое Идентификатор ненайденного объекта

Пример: изменение геометрии объекта в слое по указанному идентификатору:



https://maps.kosmosnimki.ru/rest/ver1/layers/EB840C54020749339EF7688E3FBD7139/update?geometry_cs=EPSG:3857&feature={Id:18433,”geometry”:{“type”:”Polygon”,”coordinates”:[[[36,51.5],[36,52],[34,52.5],[36,51.5]]]}}&api_key=API_KEY

Изменение нескольких объектов векторного слоя

URL: /rest/ver1/layers/layer_id/update

Параметры запроса:

Параметр Тип Описание
api_key * Строка API-ключ пользователя
features * массив JSON-объектов Изменяемые объекты. Объекты должены иметь свойство id – целочисленный идентификатор изменяемой записи.
Объекты могут иметь свойства geometry (в формате GeoJson) и properties (в формате JSON);
названия и типы атрибутов должны соответствовать атрибутам слоя.
Если соответсвующий атрибут отсутствует в слое, то он будет проигнорирован.
geometry_cs Строка Формат входной системы координат свойства geometry, возможные значения: EPSG:4326 (по умолчанию), EPSG:3395, EPSG:3857

Данные в ответе: если операция выполнена успешно, то результат пустой. Если хотя бы один объект не был найден, то результатом является JSON-объект со свойствами:

Свойство Тип Описание
warning Строка Сообщение о некорректной работе
ids Массив целых Список идентификаторов ненайденных объектов

Пример: изменение атрибутов нескольких объектов в слое по указанным идентификаторам:



https://maps.kosmosnimki.ru/rest/ver1/layers/EB840C54020749339EF7688E3FBD7139/update?features=[{"id":18432,"properties":{"SceneID":"PM1_2014_12_12","Sensor":"AQUA"}},{"id":18433,"properties":{"SceneID":"PM1_2014_12_13","Sensor":"AQUA"}}]&api_key=API_KEY

Удаление объекта векторного слоя

URL: /rest/ver1/layers/layer_id/delete

Параметры запроса:

Параметр Тип Описание
api_key * Строка API-ключ пользователя
feature * JSON-объект Удаляемый объект. Объект должен иметь свойство id – целочисленный идентификатор изменяемой записи.

Данные в ответе: если операция выполнена успешно, то результат пустой. Если объект не был найден, то результатом является JSON-объект со свойствами:

Свойство Тип Описание
warning Строка Сообщение о некорректной работе
id Целое Идентификатор ненайденного объекта

Пример: удаление объекта в слое по указанному идентификатору:


https://maps.kosmosnimki.ru/rest/ver1/layers/EB840C54020749339EF7688E3FBD7139/delete?feature={Id:18432}&api_key=API_KEY

Удаление нескольких объектов векторного слоя

URL: /rest/ver1/layers/layer_id/delete

Параметры запроса:

Параметр Тип Описание
api_key * Строка API-ключ пользователя
features * массив JSON-объектов Удаляемые объекты. Объекты должены иметь свойство id – целочисленный идентификатор изменяемой записи.

Данные в ответе: если операция выполнена успешно, то результат пустой. Если хотя бы один объект не был найден, то результатом является JSON-объект со свойствами:

Свойство Тип Описание
warning Строка Сообщение о некорректной работе
ids Массив целых Список идентификаторов ненайденных объектов

Пример: удаление нескольких объектов в слое по указанным идентификаторам:


https://maps.kosmosnimki.ru/rest/ver1/layers/EB840C54020749339EF7688E3FBD7139/delete?features=[{Id:18432},{Id:18433}]&api_key=API_KEY

Описание фильтра поиска объектов векторного слоя

Фильтр служит для поиска объектов по заданным критериям и является логическим
выражением, применяемым к объектам. В состав могут входить: названия полей слоя,
стоковых и числовых констант, операторов и скобок. Строковые константы являются
регистронезависимыми.

Часть выражения Описание Примеры
Операторы сравнения
< <= > >= <> =
Используются для сравнения числовых или строковых операндов –
частей запроса
[value] < 10
[x] <> [y]
Названиия полей Используются для именования полей, на которые накладываются
ограничения. Название должно быть заключено в двойные кавычки либо квадратные
скобки, регистр не имеет значения
[Name]
“Id”
Строковые константы Используются для задания константных операндов выражения типа
строки, даты и времени. Значение константы должно быть заключено в одинарные
кавычки. Для задания даты и времени следует использовать заданный формат
'Хельсинки'
'2015-01-15'
'13:00:00'
'15.01.2015 13:00'
Числовые константы Используются для задания константных операндов выражения типа
целого и вещественного чисел. Используются без кавычек, разделитель дробной части – точка
365
-3.14
Арифметические операторы
+ – * /
Используются для формирования комплексных ограничений с числовыми константами и полями;
плюс имеет значение конкатенации при использовании со строковыми константами и полями
[value] * 0.5
[x]-3
'район ' + [District]
Оператор CONTAINS Используется для проверки, что одна строка содержит другую. Не зависит от регистра ‘Российская Федерация’ CONTAINS ‘рация’
Оператор STARTWITH Используется для проверки, что одна строка начинается с другой. Не зависит от регистра [Country] STARTWITH ‘рос’
Логические операторы OR, AND Используются для объединения двух частей в составе сложного выражения [value] < 10 AND [value] > 0
[x] <> 0 OR [y] <> 0
Оператор приоритета () Используется для увеличивают приоритет выражения в скобках [value] < 10 AND ([x] <> 0 OR [y] <> 0)

Форматы значений свойств, используемых при создании и изменении объектов векторного слоя

Помимо указанных ниже атрибуты могут иметь null-значения.

Тип Формат
String JSON-строка
Integer JSON-число без вещественной части
Float JSON-число
Date Может быть представлено числом (unix timestamp) или строкой. Строка должна иметь один из следующих форматов:

YYYY-MM-DD<br/>DD.MM.YYYY<br/>MM/DD/YYYY
YYYY-MM-DD<br/>DD.MM.YYYY<br/>MM/DD/YYYY
Time Должно быть представлено строкой в формате
hh:mm[:ss[.ms]][Z | +hh[:mm] | -hh[:mm] ]]
hh:mm[:ss[.ms]][Z | +hh[:mm] | -hh[:mm] ]]
DateTime Может быть представлено числом (unix timestamp) или строкой. Строка должна иметь формат:

дата[[T | _(пробел)]время]
дата[[T | _(пробел)]время]

, где дата и время представлены в форматах Date и Time соответсвенно

Boolean Может быть одно из значений:
true | 1 | false | 0
true | 1 | false | 0

Работа с асинхронными задачами

Далее везде task_id обозначает идентификатор задачи, полученный от метода,
инициировавшего выполнение.

Состояние задачи

URL: /rest/ver1/tasks/task_id

Параметры запроса:

Запрос не содержит параметров.

Данные в ответе: если задача была найдена, то результатом является JSON-объект со свойствами:

Свойство Тип Описание
TaskID Строка Идентификатор задачи
Completed Строка Состояние завершенности задачи, возможные значения: true (окончена) или false
(обрабатывается). Поля Result и ErrorInfo имеют значения, если операция
завершена.
Result JSON-объект Результат операции, если она завершена
ErrorInfo JSON-объект Ошибка выполнения асинхронной операции

Пример: проверка состояния задачи:


http://maps.kosmosnimki.ru/rest/ver1/tasks/988B6B6545B04F8B93D30CACE2B1F757S_AE0D3E0786A9400481E78FA9B899510AT?api_key=API_KEY