Geofence
Named map areas that limit where a rule applies and that name locations in reports.
A geofence is a named area on the map. The API calls it a zone in paths and field names: the path is /zone, the object is Zone, and a rule binds to one through zone_ids.
Geofences limit where a rule applies. A rule that names a geofence reacts only to events inside it. Geofence names also reach reports, printed after the address of an event that happened inside the geofence.
Points belong to polygons and sausages, and a single geofence can carry hundreds of them. The operations that read and write points are on their own page for that reason, Geofence point. To create many circle geofences at once from a spreadsheet, use Geofence import. For step-by-step instructions on each type, see how to create each geofence type.
Entity description
A zone object carries a type of circle, polygon, or sausage. The type determines which of the remaining fields apply.
circle
A centre and a radius. Carries center and radius, and has no points.
polygon
An area bounded by points. Carries points and no radius.
sausage
Represents all points within a certain distance of the given polyline. Carries both points and a radius, the radius being the distance from the line.
API actions
API base path: /zone.
Operations that list no errors of their own return only the general error codes.
Preload the file that file_id names with data/spreadsheet/parse, which converts a spreadsheet to a tab-separated file and returns its name.
Required sub-user rights: zone_update.
Parse a tab-delimited batch of circle geofences and return them checked, with per-row errors. Creates nothing.
Give either batch or file_id. If file_id is set, batch is ignored. A request with neither returns error 7 with the message "The 'batch' or 'file_id' parameter must be specified".
Within a row, address is required when coordinates are absent, and lat and lng are required when the address is absent.
Requires the zone_update right.
Either a user session hash or an API key, with the "NVX " prefix, for example "NVX 22eac1c27af4be7b9d04da2ce1af111b". Obtain a session hash from the userAuth operation, or create an API key from the API keys operations. A small number of operations accept a session hash only and reject an API key with error code 4; each says so in its description.
Batch of tab-delimited geofences.
ID of a file preloaded with data/spreadsheet/parse. Takes precedence over batch.
Optional. Column names, in order. Defaults to ["label", "address", "lat", "lng", "radius", "tags"].
Optional. Geocoder type to use for resolving addresses.
Optional. Default 100. Radius in metres for a row that gives none.
The checked batch
true if request finished successfully.
truetrue if the given batch was constrained by a limit.
Bad request. The response body carries the API-level error code in status.code. Validation failures also include an errors array naming each offending parameter.
Error 234: the batch or file could not be parsed.
Error response object
POST /v2/zone/batch_convert HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 88
{
"batch": "text",
"file_id": "text",
"fields": [
"text"
],
"geocoder": "text",
"default_radius": 1
}{
"success": true,
"list": [
{
"id": 1,
"type": "circle",
"label": "text",
"address": "text",
"color": "text",
"radius": 1,
"center": {
"lat": 1,
"lng": 1
},
"points": [
{
"lat": 1,
"lng": 1,
"node": true
}
],
"bounds": {
"nw": {
"lat": 1,
"lng": 1
},
"se": {
"lat": 1,
"lng": 1
}
},
"tags": [
1
],
"errors": [
{
"parameter": "text",
"error": "text"
}
],
"ANY_ADDITIONAL_PROPERTY": "anything"
}
],
"limit_exceeded": true
}Errors
These errors come in addition to the general error codes:
234 - Invalid data format.
Required sub-user rights: zone_update.
Create a geofence, and return its ID.
Pass the zone object without id. color is optional and defaults to 27A9E3.
Points go in the separate points parameter rather than inside the zone object, and must be omitted entirely for a circle, which cannot have any. A polygon needs at least 3 points and allows at most 500. A sausage needs at least 2 and allows at most 1024. A circle takes no points at all.
Requires the zone_update right.
Either a user session hash or an API key, with the "NVX " prefix, for example "NVX 22eac1c27af4be7b9d04da2ce1af111b". Obtain a session hash from the userAuth operation, or create an API key from the API keys operations. A small number of operations accept a session hash only and reject an API key with error code 4; each says so in its description.
The created geofence
true if request finished successfully.
trueID of the new geofence.
Bad request. The response body carries the API-level error code in status.code. Validation failures also include an errors array naming each offending parameter.
Error 268: the user's quota for geofences is exhausted.
Error 202: too many points, above 500 for a polygon or 1024 for a sausage. Error 230: points were given for a geofence type that cannot have them, such as a circle. Error 284: not enough points, below 3 for a polygon or 2 for a sausage.
Error response object
POST /v2/zone/create HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 268
{
"zone": {
"id": 1,
"type": "circle",
"label": "text",
"address": "text",
"color": "text",
"radius": 1,
"center": {
"lat": 1,
"lng": 1
},
"points": [
{
"lat": 1,
"lng": 1,
"node": true
}
],
"bounds": {
"nw": {
"lat": 1,
"lng": 1
},
"se": {
"lat": 1,
"lng": 1
}
},
"tags": [
1
]
},
"points": [
{
"lat": 1,
"lng": 1,
"node": true
}
]
}{
"success": true,
"id": 1
}Errors
These errors come in addition to the general error codes:
202 - Too many points in a geofence. A polygon allows at most 500 points and a sausage at most 1024.
230 - Not supported for this entity type, when
pointswere given for a geofence that cannot hold any, such as a circle.268 - Over quota, when the user's quota for geofences is exceeded.
284 - Not enough points for the geofence. A polygon needs at least 3 points and a sausage at least 2.
Required sub-user rights: zone_update.
Delete one geofence or several by ID.
Give either zone_id or zone_ids. A request with neither reports the message "There must be one of the parameters - zone_id or zone_ids" against zone_ids.
Error 203 carries data. A geofence still referenced by rules cannot be deleted, and the response body includes an entities array naming the type and the IDs that reference it, so a caller can go and clear them.
Requires the zone_update right.
Also accepts GET with the same parameters as query-string values.
Either a user session hash or an API key, with the "NVX " prefix, for example "NVX 22eac1c27af4be7b9d04da2ce1af111b". Obtain a session hash from the userAuth operation, or create an API key from the API keys operations. A small number of operations accept a session hash only and reject an API key with error code 4; each says so in its description.
ID of a single geofence to delete. Use this or zone_ids, not both.
IDs of geofences to delete. Use this or zone_id, not both.
Geofences deleted
true if request finished successfully.
trueBad request. The response body carries the API-level error code in status.code. Validation failures also include an errors array naming each offending parameter.
Error 203: the geofence is still associated with something, normally a rule. The response body carries an entities array naming the referencing type and IDs.
Error response object
POST /v2/zone/delete HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 28
{
"zone_id": 1,
"zone_ids": [
1
]
}{
"success": true
}Errors
These errors come in addition to the general error codes:
201 - Not found in the database.
203 - Delete entity associated with. The response body names what still references the geofence:
ids is an int array holding the IDs of the rules that use the geofence.
List the geofences of the current user, with filtering and pagination.
Points are left out unless with_points is set, because a polygon or sausage can carry hundreds of them.
Callable with an empty body. Also accepts GET with the same parameters as query-string values.
Either a user session hash or an API key, with the "NVX " prefix, for example "NVX 22eac1c27af4be7b9d04da2ce1af111b". Obtain a session hash from the userAuth operation, or create an API key from the API keys operations. A small number of operations accept a session hash only and reject an API key with error code 4; each says so in its description.
Optional. Filter over geofence label and description.
Optional. Tag IDs. A geofence must carry all the tags in the list to be returned.
Optional. Offset into the found geofences, for pagination.
Optional. Number of geofences to return.
Optional. Default false. Include each geofence's points.
Matching geofences
true if request finished successfully.
trueTotal number of geofences matching the filter, ignoring pagination. ZoneListAction returns a ListWithCountResponse, so this is always present.
Bad request. The response body carries the API-level error code in status.code. Validation failures also include an errors array naming each offending parameter.
Error response object
POST /v2/zone/list HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 71
{
"filter": "text",
"tag_ids": [
1
],
"offset": 1,
"limit": 1,
"with_points": true
}{
"success": true,
"list": [
{
"id": 1,
"type": "circle",
"label": "text",
"address": "text",
"color": "text",
"radius": 1,
"center": {
"lat": 1,
"lng": 1
},
"points": [
{
"lat": 1,
"lng": 1,
"node": true
}
],
"bounds": {
"nw": {
"lat": 1,
"lng": 1
},
"se": {
"lat": 1,
"lng": 1
}
},
"tags": [
1
]
}
],
"count": 1
}Return one geofence by ID.
Points are left out unless with_points is set.
Also accepts GET with the same parameters as query-string values.
Either a user session hash or an API key, with the "NVX " prefix, for example "NVX 22eac1c27af4be7b9d04da2ce1af111b". Obtain a session hash from the userAuth operation, or create an API key from the API keys operations. A small number of operations accept a session hash only and reject an API key with error code 4; each says so in its description.
ID of the geofence.
Optional. Default false. Include the geofence's points.
The geofence
true if request finished successfully.
trueBad request. The response body carries the API-level error code in status.code. Validation failures also include an errors array naming each offending parameter.
Error response object
POST /v2/zone/read HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 32
{
"zone_id": 1,
"with_points": true
}{
"success": true,
"value": {
"id": 1,
"type": "circle",
"label": "text",
"address": "text",
"color": "text",
"radius": 1,
"center": {
"lat": 1,
"lng": 1
},
"points": [
{
"lat": 1,
"lng": 1,
"node": true
}
],
"bounds": {
"nw": {
"lat": 1,
"lng": 1
},
"se": {
"lat": 1,
"lng": 1
}
},
"tags": [
1
]
}
}Return the ID and name of every geofence whose area contains the given coordinates.
The place equivalent is place/search_location.
Either a user session hash or an API key, with the "NVX " prefix, for example "NVX 22eac1c27af4be7b9d04da2ce1af111b". Obtain a session hash from the userAuth operation, or create an API key from the API keys operations. A small number of operations accept a session hash only and reject an API key with error code 4; each says so in its description.
Geofences containing the point
true if request finished successfully.
trueBad request. The response body carries the API-level error code in status.code. Validation failures also include an errors array naming each offending parameter.
Error response object
POST /v2/zone/search_location HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 30
{
"location": {
"lat": 1,
"lng": 1
}
}{
"success": true,
"list": [
{
"id": 1,
"label": "text"
}
]
}A points array inside the zone object is applied with the rest of the update. zone/point/update does the same thing on its own.
Required sub-user rights: zone_update.
Update a geofence. Pass the zone object with its id.
The type cannot be changed. A geofence stored as a circle cannot be submitted as a polygon, and trying returns error 231.
For a polygon or sausage, including a points array inside the zone object updates the points. zone/point/update does the same thing on its own.
Requires the zone_update right.
Either a user session hash or an API key, with the "NVX " prefix, for example "NVX 22eac1c27af4be7b9d04da2ce1af111b". Obtain a session hash from the userAuth operation, or create an API key from the API keys operations. A small number of operations accept a session hash only and reject an API key with error code 4; each says so in its description.
Geofence updated
true if request finished successfully.
trueBad request. The response body carries the API-level error code in status.code. Validation failures also include an errors array naming each offending parameter.
Error 231: the submitted type differs from the stored type.
Error response object
POST /v2/zone/update HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 227
{
"zone": {
"id": 1,
"type": "circle",
"label": "text",
"address": "text",
"color": "text",
"radius": 1,
"center": {
"lat": 1,
"lng": 1
},
"points": [
{
"lat": 1,
"lng": 1,
"node": true
}
],
"bounds": {
"nw": {
"lat": 1,
"lng": 1
},
"se": {
"lat": 1,
"lng": 1
}
},
"tags": [
1
]
}
}{
"success": true
}Errors
These errors come in addition to the general error codes:
201 - Not found in the database, when no geofence has the given ID or it belongs to another user.
231 - Entity type mismatch, when the submitted geofence's type differs from the type stored in the database.
The upload accepts a KML file whose Placemark elements define the geofences. A radius given in ExtendedData applies to the circles the file produces, and a Placemark without one takes the default radius:
A Placemark name becomes the geofence name, and the Folder and Document hierarchy around it is preserved.
Required sub-user rights: zone_update.
Import geofences from a KML file.
This is a multipart request, not JSON: multipart/form-data with the KML in a part named file.
dry_run defaults to true, so a plain call validates and returns the geofences it would create without creating anything. Set it to false to create them, which returns their IDs instead.
A Placemark with Point geometry becomes a circle, taking its radius from the placemark's extended data or from default_radius. A Placemark with MultiGeometry becomes several geofences. Where Placemark.name is set it becomes the geofence name, respecting any Folder and Document hierarchy.
Requires the zone_update right.
Either a user session hash or an API key, with the "NVX " prefix, for example "NVX 22eac1c27af4be7b9d04da2ce1af111b". Obtain a session hash from the userAuth operation, or create an API key from the API keys operations. A small number of operations accept a session hash only and reject an API key with error code 4; each says so in its description.
The KML file of geofences.
Default radius in metres for a circle or route geofence. Minimum 20, default 150.
Default true. When true, return the geofences that would be created without creating them. When false, create them and return their IDs.
Optional. URL to redirect to after the upload.
The geofences that would be created, or the IDs of those created
true if request finished successfully.
trueBad request. The response body carries the API-level error code in status.code. Validation failures also include an errors array naming each offending parameter.
Error 233: the file part is missing. Error 234: the file could not be parsed. Error 268: the user's quota for geofences is exhausted.
Error 202: too many points, above 500 for a polygon or 1024 for a sausage. Error 284: not enough points, below 3 for a polygon or 2 for a sausage.
Error response object
POST /v2/zone/upload HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Content-Type: multipart/form-data
Accept: */*
Content-Length: 76
{
"file": "binary",
"default_radius": 1,
"dry_run": true,
"redirect_target": "text"
}{
"success": true,
"list": []
}Errors
These errors come in addition to the general error codes:
202 - Too many points in a geofence. A polygon allows at most 500 points and a sausage at most 1024.
233 - No data file, when the
filepart is missing.234 - Invalid data format.
268 - Over quota, when the user's quota for geofences is exceeded.
284 - Not enough points for the geofence. A polygon needs at least 3 points and a sausage at least 2.
The response is a KML or KMZ file holding one Placemark per geofence, with the radius of a circle or a sausage carried in ExtendedData:
Return geofences as a KML or KMZ file.
The response is the file itself, not a JSON envelope. Both parameters are optional, so an empty body downloads every available geofence as KML.
Either a user session hash or an API key, with the "NVX " prefix, for example "NVX 22eac1c27af4be7b9d04da2ce1af111b". Obtain a session hash from the userAuth operation, or create an API key from the API keys operations. A small number of operations accept a session hash only and reject an API key with error code 4; each says so in its description.
Optional. Default kml. File format.
Optional. Geofences to include. When null, every available geofence is downloaded.
The geofences as a KML or KMZ file
Bad request. The response body carries the API-level error code in status.code. Validation failures also include an errors array naming each offending parameter.
Error response object
POST /v2/zone/download HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 31
{
"format": "kml",
"zone_ids": [
1
]
}binaryMore in this section
Geofence import
Geofence point
Last updated
Was this helpful?