Geo zones

Geo zones are some of the selected areas on the map. They can be constructed in a platform of different shapes. t can be a rectangle, a polygon, a circle, a marker, a segment. However, regardless of the chosen shape, the boundaries of any geo zones are based on coordinates. Accordingly, the configuration description of the geo zone, which can be obtained through the API, is a list of points, each of which indicates the boundary of the geo zone and has certain coordinates.

As with any other entity, the following list of actions when interacting with them through the API can be reproduced with geo zones:

1. Getting a list of geo zones.
2. Getting information about one geo zone.
3. Creating a new geo zone.
4. Changing a geo zone.
5. Deleting a geo zone.

Getting a list of geo zones

In order to get a complete list of geo zones available to the user, you need to send a request  GET /api/v1/geofences. The response will provide an array of objects, each of which represents a configuration of a separate geo zones.

Request

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

Response

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

Getting information about one geo zone

In order to get the configuration of a specific geo zone, just add the _id prefix by indicating its identification number.  In response, the required geo zone configuration, and the result of the request will be received.

Request

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

Response

HTTP/1.1 200 OK

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

Creating a new geo zone

Unlike other entities of the system, when creating a new geo zone, it is necessary to take into account the kind of geo zone that should be created. In particular, one of six forms can be selected for a geo zone, each of which is configured in its own way.

Accordingly, if the user selected the shape of a polygon or rectangle, then in this case it is required to indicate the coordinates of all the corners of the selected figure. If the user decided to create a circle, then it is necessary to take into account the coordinates of its center and the radius, measured in meters. Similarly, the coordinates are indicated for the marker and for all points of the broken line, which are listed in the same way as the corners of the polygon.

Below there is an example of adding a geo zone in the form of a polygon.

Request

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

Response

HTTP/1.1 200 OK

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

Changing a geo zone

To change the value of any fields of the geo zone, it is necessary to send a request PATCH /api/v1/geofences/:id, in the body of which the new required value should be indicated. The response will receive a new configuration, taking into account the changes made and the result of processing the request.

Request

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

{
  "color": "#5e833c"
}

Response

HTTP/1.1 200 OK

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

Deleting a geo zone

To delete a geo zone, you must use the DELETE method and specify its identifier. The response from the webserver will receive the configuration of the remote entity and the result of the request.

Request

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

Response

HTTP/1.1 200 OK

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