update_zone
To create, edit, or delete geofences, use the resource/update_zone method.
Endpoint
svc=resource/update_zone¶ms={
"itemId": <long>,
"id": <long>,
"callMode": "<text>",
"n": "<text>",
"d": "<text>",
"t": <uint>,
"w": <uint>,
"f": <uint>,
"c": <uint>,
"tc": <uint>,
"ts": <uint>,
"min": <uint>,
"max": <uint>,
"path": "<text>",
"libId": <long>,
"oldItemId": <long>,
"oldZoneId": <uint>,
"jp": <JSON>,
"p": [
{
"x": <double>,
"y": <double>,
"r": <uint>
}
]
}
Parameters
The itemId, id, and callMode parameters are required for all actions. For create and update, the n, t, w, f, c, and p parameters are also required, and the other parameters are optional. For delete and reset_image, only itemId, id, and callMode are used.
| Parameter | Description |
|---|---|
itemId |
Resource ID. |
id |
Geofence ID. For create, the value isn’t used, so specify 0. |
callMode |
Action: create, update, delete, or reset_image (delete the geofence image or icon). |
oldItemId |
The ID of the resource from which the geofence image should be copied. Optional. It’s used only together with oldZoneId. |
oldZoneId |
The ID of the geofence whose image should be copied. Optional. It’s used only together with oldItemId. |
n |
Name. |
d |
Description. Optional. If it isn’t specified, the description is empty. When you update a geofence, this deletes its current description. |
t |
Geofence type:
|
w |
Line width. For a circle, this is the radius. The value is in feet if the resource uses the US or imperial measurement system, and in meters otherwise. |
f |
Flags (see Geofence flags). |
c |
Color (ARGB). |
tc |
Text color (RGB). Optional. The default value is 16711884 (0xFF00CC). |
ts |
Text size. Optional. The default value is 12. |
min |
Minimum scale (visibility from). Optional. The default value is 0. |
max |
Maximum scale (visibility to). Optional. The default value is 4294967295 (0xFFFFFFFF). |
path |
Icon path. Optional. |
libId |
Icon library ID. Optional. The default value is 0 (the default icon library). |
jp |
Custom fields in the name:value format. Optional. |
p |
Points, where x is the longitude, y is the latitude, and r is the radius. Each point must contain all three values. A line must have at least 2 points, a polygon at least 3, and a circle exactly 1. Points with invalid coordinates are skipped. For a circle, the radius is taken from w, and r is ignored. The units of r are the same as the units of w. |
When you update a geofence, the tc, ts, min, max, path, libId, and jp parameters that aren’t specified keep their current values. The geofence image or icon is also kept. When you create a geofence, the default values are used instead.
To copy the image of another geofence, specify the
oldItemIdandoldZoneIdparameters. Only the image or icon of the source geofence is copied. The other properties (for example, the text color or custom fields) are taken from the request, so specify them explicitly. The user must have the View geofences access right to the source resource.
For more information about geofence properties, see resource/get_zone_data.
Geofence flags
The following geofence flags (f) are available:
| Flag | Description |
|---|---|
0x2 |
Geofence where a ride begins. It’s used in reports if the start and end geofences of rides aren’t specified in the table settings. |
0x4 |
Geofence where a ride ends. It’s used in reports if the start and end geofences of rides aren’t specified in the table settings. |
0x10 |
Set automatically when the geofence is saved. |
0x20 |
Show shape. |
0x40 |
Don’t simplify the geofence. |
The 0x10 flag is always added to the saved value. The 0x20 flag is also added if the request contains none of the tc, ts, min, max, libId, path, and jp parameters. For example, if you specify "f": 0 without these parameters, the geofence is saved with the 48 (0x30) flags value.
Response
If a create, update, or reset_image request is completed successfully, the response is returned in the following format:
[
<long>, /* geofence ID */
{
"n": "<text>", /* name */
"d": "<text>", /* description */
"id": <long>, /* geofence ID */
"f": <uint>, /* flags */
"t": <int>, /* type: 1 (line), 2 (polygon), 3 (circle) */
"w": <int>, /* line width or circle radius, in feet or meters depending on the measurement system of the resource */
"e": <ushort>, /* checksum of the geofence data (CRC16) */
"c": <uint>, /* color (ARGB) */
"i": <uint>, /* checksum of the image (CRC32); 4294967295 if the geofence has no image of its own */
"icon": "<text>", /* icon image URI; returned only if the geofence has an image or an icon from the library */
"libId": <long>, /* ID of the icon library, 0 for the default icon library */
"path": "<text>", /* short path to the icon from the icon library; empty if the geofence has no such icon */
"b": { /* limits */
"min_x": <double>, /* minimum longitude */
"min_y": <double>, /* minimum latitude */
"max_x": <double>, /* maximum longitude */
"max_y": <double>, /* maximum latitude */
"cen_x": <double>, /* the longitude of the center */
"cen_y": <double> /* the latitude of the center */
},
"ct": <uint>, /* creation time */
"mt": <uint>, /* last modification time */
"jp": <JSON> /* custom JSON; returned only if it's specified for the geofence */
}
]
The response doesn’t contain the tc, ts, min, max, and p fields. To get them, use resource/get_zone_data.
For the geofence flags, see Geofence flags.
If a delete request is completed successfully, the response is returned in the following format:
[
<long>, /* geofence ID */
null
]
If the request fails, an error code is returned.
Error codes
| Error code | Description |
|---|---|
| 4 | Wrong input parameters. If a required parameter is missing or has a wrong type, the response also contains the reason. If the callMode value, the geofence type, or the number of points is invalid, only the error code is returned. |
| 6 | The geofence with the specified ID doesn’t exist in the resource, or it couldn’t be deleted, or its image couldn’t be reset. |
| 7 | The item with the specified ID doesn’t exist or isn’t a resource, or the user has no Create, edit, and delete geofences access right to the resource. When you copy an image, this error is also returned if the source resource or geofence doesn’t exist, or if the user has no View geofences access right to the source resource. |