Геозоны

Геозоны представляют собой некоторые выделенные участки на карте. Они могут быть построены в платформе различной формы. Это может быть прямоугольник, многоугольник, круг, маркер, отрезок. Однако независимо от выбранной формы границы любой геозоны строятся на основе координат. Соответственно, конфигурационное описание геозоны, которое может быть получено через API, представляет собой некоторый список точек, каждая из которых обозначает границу геозоны и обладает определенными координатами.

Как и с любой другой сущностью, с геозонами может быть воспроизведен следующий список действий при взаимодействии с ними через API:

  1. Получение списка геозон.
  2. Получение информации об одной геозоне.
  3. Создание новой геозоны.
  4. Изменение геозоны.
  5. Удаление геозоны.

Получение списка геозон

Для того чтобы получить полный список геозон, доступных пользователю, необходимо отправить запрос GET /api/v1/geofences. В ответе будет получен массив объектов, каждый из которых представляет собой конфигурацию отдельной геозоны.

Запрос

GET /api/v1/geofences HTTP/1.1
Content-Type: application/json
Authorization: Bearer {token}

Ответ

HTTP/1.1 200 OK

[
    {
        "_id": "5d8ce44fc82fdf0011280a58",
        "name": "Геозона 01",
        "description": "Описание геозоны 01",
        "shape": {
            "type": "rectangle",
            "points": [
                [
                    55.783300490801025,
                    37.66964077949524
                ],
                [
                    55.78409685007678,
                    37.66964077949524
                ],
                [
                    55.78409685007678,
                    37.67459750175476
                ],
                [
                    55.783300490801025,
                    37.67459750175476
                ]
            ]
        },
        "color": "#ec7832"
    },
    {
        "_id": "5d8ce469c82fdf0011280a8f",
        "name": "Геозона 02",
        "description": "Описание геозоны 02",
        "color": "#6c3b7b",
        "shape": {
            "type": "circle",
            "center": [
                55.781146619399635,
                37.67145395278931
            ],
            "radius": 153.8626808920941
        }
    }
]

Получение информации об одной геозоне

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

Запрос

GET /api/v1/geofences/:id HTTP/1.1
Content-Type: application/json
Authorization: Bearer {token}

Ответ

HTTP/1.1 200 OK

{
    "_id": "5d8ce550c82fdf0011280c75",
    "name": "Маркер 03",
    "description": "На Краснопрудной улице",
    "color": "#5e833c",
    "shape": {
        "type": "marker",
        "center": [
            55.7777918934897,
            37.662291526794434
        ]
    },
    "success": true
}

Создание новой геозоны

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

Соответственно, если пользователем была выбрана форма многоугольника или прямоугольника, то в этом случае требуется указать координаты всех углов выбранной фигуры. Если пользователь решил построить круг, то тогда необходимо учитывать координаты его центра и радиус, измеряемый в метрах. Аналогично координаты указываются для маркера и для всех точек ломанной, которые перечисляются так же, как и углы многоугольника.

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

Запрос

POST /api/v1/geofences HTTP/1.1
Content-Type: application/json
Authorization: Bearer {token}

{
  "name": "Многоугольник 05",
  "shape": {
        "type": "polygon",
        "points": [
      [
        55.77267477694781,
              37.675960063934326
          ],
          [
              55.77314548317715,
              37.67838478088379
          ],
          [
              55.77543858606823,
              37.677719593048096
          ],
          [
              55.77728503928302,
              37.673985958099365
          ],
          [
              55.775981669624315,
              37.67093896865845
          ]
      ]
  },
    "color": "#ec7832"
}

Ответ

HTTP/1.1 200 OK

{
    ... /* параметры многоугольника, указанные в запросе */
    "owner": "5d8a18d5d0025e0012fb6a34",
    "group": "5d8a18d4d0025e0012fb6a31",
    "time": 1569515798632,
    "_id": "5d8ce916c82fdf0011281472",
    "success": true
}

Изменение геозоны

Для изменения значения каких-либо полей геозоны необходимо отправить запрос PATCH /api/v1/geofences/:id, в теле которого должно быть указано новое требуемое значение. В ответе будет получена новая конфигурация с учетом внесенных изменений и результат обработки запроса.

Запрос

PATCH /api/v1/geofences/:id HTTP/1.1
Content-Type: application/json
Authorization: Bearer {token}

{
  "color": "#5e833c"
}

Ответ

HTTP/1.1 200 OK

{
    "_id": "5d8ce916c82fdf0011281472",
    "name": "Многоугольник 05",
    "shape": {
        ...
    },
    "color": "#5e833c",
    "owner": "5d8a18d5d0025e0012fb6a34",
    "group": "5d8a18d4d0025e0012fb6a31",
    "time": 1569515798632,
    "_at": 1569516306748,
    "success": true
}

Удаление геозоны

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

Запрос

DELETE /api/v1/geofences/:id HTTP/1.1
Content-Type: application/json
Authorization: Bearer {token}

Ответ

HTTP/1.1 200 OK

{
    "_id": "5d8cec3fc82fdf0011281b11",
    "name": "Отрезок 06",
    "description": "Старая Басманная улица",
    "color": "#424850",
    "shape": {
        ...
    },
    "owner": "5d8a18d5d0025e0012fb6a34",
    "group": "5d8a18d4d0025e0012fb6a31",
    "time": 1569516607782,
    "success": true
}