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:
- Getting a list of geo zones.
- Getting information about one geo zone.
- Creating a new geo zone.
- Changing a geo zone.
- 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
}