Geofence

Geofence are some of the selected areas on the map. They can be constructed in a platform of different shapes. It can be a rectangle, a polygon, a circle, a marker, a segment. However, regardless of the chosen shape, the boundaries of any geofence are based on coordinates. Accordingly, the configuration description of the geofence, which can be obtained through the API, is a list of points, each of which indicates the boundary of the geofence 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 geofence:

1. Getting a list of geofences.
2. Getting information about one geofence.
3. Creating a new geofence.
4. Changing a geofence.
5. Deleting a geofence.

Getting a list of geofences

In order to get a complete list of geofences 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 separate geofences.

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 geofence

In order to get the configuration of a specific geofence, just add the _id prefix by indicating its identification number.  In response, the required geofence 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 geofence

Unlike other entities of the system, when creating a new geofence, it is necessary to take into account the kind of geofence that should be created. In particular, one of six forms can be selected for a geofence, 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 geofence 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 geofence

To change the value of any fields of the geofence, 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 geofence

To delete a geofence, 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
}