> For the complete documentation index, see [llms.txt](https://navixy.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://navixy.com/docs/navixy-api/user-api/resources/tracking/zone.md). # 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](/docs/navixy-api/user-api/resources/tracking/zone/zone_point.md). To create many circle geofences at once from a spreadsheet, use [Geofence import](/docs/navixy-api/user-api/resources/tracking/zone/import.md). For step-by-step instructions on each type, see [how to create each geofence type](/docs/navixy-api/user-api/guides/places/manage-geofences.md). ## Entity description A zone object carries a `type` of `circle`, `polygon`, or `sausage`. The type determines which of the remaining fields apply. ## The Zone object ```json {"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"components":{"schemas":{"Zone":{"type":"object","description":"A geofence: an area used to limit where a rule applies, and named after the address in reports when an event happens inside it.\n\n**One object, three shapes, selected by `type`.** A `circle` has `center` and `radius`. A `polygon` has `points`. A `sausage` has `points` and a `radius`, and covers everything within that distance of the polyline.","properties":{"id":{"type":"integer","description":"Geofence ID. Absent when creating."},"type":{"type":"string","description":"Which shape this geofence is, and therefore which of the fields below apply. **Cannot be changed** once the geofence exists.","enum":["circle","polygon","sausage"]},"label":{"type":"string","description":"Geofence label."},"address":{"type":"string","description":"Geofence address."},"color":{"type":"string","description":"Geofence colour, as a three-byte RGB hex value. Optional on create and update, defaulting to `27A9E3`."},"radius":{"type":"integer","description":"Radius in metres. **For `circle` it is the circle radius; for `sausage` it is the distance from the polyline. A `polygon` has no radius.**"},"center":{"type":"object","description":"Centre of the circle. **`circle` only.**","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."}}},"points":{"type":"array","description":"The geofence points. **`polygon` and `sausage` only**, and returned only when the operation was asked for them. On create they go in a separate `points` parameter instead.","items":{"$ref":"#/components/schemas/ZonePoint"}},"bounds":{"type":"object","description":"North-west and south-east corners of the axis-aligned minimum bounding box.","properties":{"nw":{"type":"object","description":"North-west corner.","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."}}},"se":{"type":"object","description":"South-east corner.","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."}}}}},"tags":{"type":"array","description":"IDs of tags applied to the geofence.","items":{"type":"integer"}}}},"ZonePoint":{"type":"object","description":"One point of a polygon or sausage geofence. A circle geofence has no points.","properties":{"lat":{"type":"number","description":"Point latitude."},"lng":{"type":"number","description":"Point longitude."},"node":{"type":"boolean","description":"`true` when this point is a route node."}}}}}} ``` ## The ZonePoint object ```json {"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"components":{"schemas":{"ZonePoint":{"type":"object","description":"One point of a polygon or sausage geofence. A circle geofence has no points.","properties":{"lat":{"type":"number","description":"Point latitude."},"lng":{"type":"number","description":"Point longitude."},"node":{"type":"boolean","description":"`true` when this point is a route node."}}}}}} ``` #### circle A centre and a radius. Carries `center` and `radius`, and has no points. #### polygon An area bounded by [points](/docs/navixy-api/user-api/resources/tracking/zone/zone_point.md). 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](/docs/navixy-api/general/errors.md#error-codes). *** Preload the file that `file_id` names with [`data/spreadsheet/parse`](/docs/navixy-api/user-api/resources/commons/data.md#post-data-spreadsheet-parse), which converts a spreadsheet to a tab-separated file and returns its name. *Required sub-user rights:* `zone_update`. ## Convert geofence batch > 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. ```json {"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Geofences","description":"Geofences of all three shapes, their points, and spreadsheet and KML import and export. All resources under the /zone/ path."}],"servers":[{"url":"https://api.eu.navixy.com/v2","description":"Navixy production server on European platform"},{"url":"https://api.us.navixy.com/v2","description":"Navixy production server on American platform"},{"url":"https://api.me.navixy.com/v2","description":"Navixy production server on Middle East platform"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","description":"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.","name":"Authorization","in":"header"}},"schemas":{"CheckedZone":{"type":"object","description":"A circle geofence parsed from a batch, with the same fields as a geofence plus any per-row problems found while checking it. `id` is null, since nothing was created.","properties":{"id":{"type":"integer","description":"Geofence ID. Absent when creating."},"type":{"type":"string","description":"Which shape this geofence is, and therefore which of the fields below apply. **Cannot be changed** once the geofence exists.","enum":["circle","polygon","sausage"]},"label":{"type":"string","description":"Geofence label."},"address":{"type":"string","description":"Geofence address."},"color":{"type":"string","description":"Geofence colour, as a three-byte RGB hex value. Optional on create and update, defaulting to `27A9E3`."},"radius":{"type":"integer","description":"Radius in metres. **For `circle` it is the circle radius; for `sausage` it is the distance from the polyline. A `polygon` has no radius.**"},"center":{"type":"object","description":"Centre of the circle. **`circle` only.**","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."}}},"points":{"type":"array","description":"The geofence points. **`polygon` and `sausage` only**, and returned only when the operation was asked for them. On create they go in a separate `points` parameter instead.","items":{"$ref":"#/components/schemas/ZonePoint"}},"bounds":{"type":"object","description":"North-west and south-east corners of the axis-aligned minimum bounding box.","properties":{"nw":{"type":"object","description":"North-west corner.","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."}}},"se":{"type":"object","description":"South-east corner.","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."}}}}},"tags":{"type":"array","description":"IDs of tags applied to the geofence.","items":{"type":"integer"}},"errors":{"type":"array","description":"Optional. Problems found in this row, present only when something is wrong.","items":{"type":"object","properties":{"parameter":{"type":"string","description":"Which parameter was wrong, such as `zone.center`."},"error":{"type":"string","description":"What was wrong with it."}}}}},"additionalProperties":true},"ZonePoint":{"type":"object","description":"One point of a polygon or sausage geofence. A circle geofence has no points.","properties":{"lat":{"type":"number","description":"Point latitude."},"lng":{"type":"number","description":"Point longitude."},"node":{"type":"boolean","description":"`true` when this point is a route node."}}}},"responses":{"ResponseError":{"description":"Error response object","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always false."},"status":{"type":"object","description":"Error status. Present only when an error occurred.","properties":{"code":{"type":"integer","description":"An error code in this API, not an HTTP code."},"description":{"type":"string","description":"An error description."}}},"errors":{"type":"array","description":"Per-parameter detail, returned with validation failures such as error code 7. A parameter name here may be an internal field name rather than the documented parameter name.","items":{"type":"object","properties":{"parameter":{"type":"string","description":"Name of the parameter that failed validation."},"error":{"type":"string","description":"What was wrong with it."}}}}}}}}}}},"paths":{"/zone/batch_convert":{"post":{"tags":["Geofences"],"summary":"Convert geofence batch","description":"Parse a tab-delimited batch of **circle** geofences and return them checked, with per-row errors. **Creates nothing.**\n\nGive 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\".\n\nWithin a row, `address` is required when coordinates are absent, and `lat` and `lng` are required when the address is absent.\n\nRequires the `zone_update` right.","operationId":"zoneBatchConvert","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"batch":{"type":"string","description":"Batch of tab-delimited geofences."},"file_id":{"type":"string","description":"ID of a file preloaded with `data/spreadsheet/parse`. Takes precedence over `batch`."},"fields":{"type":"array","description":"Optional. Column names, in order. Defaults to `[\"label\", \"address\", \"lat\", \"lng\", \"radius\", \"tags\"]`.","items":{"type":"string"}},"geocoder":{"type":"string","description":"Optional. Geocoder type to use for resolving addresses."},"default_radius":{"type":"integer","description":"Optional. Default 100. Radius in metres for a row that gives none."}}}}}},"responses":{"200":{"description":"The checked batch","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true},"list":{"type":"array","items":{"$ref":"#/components/schemas/CheckedZone"}},"limit_exceeded":{"type":"boolean","description":"`true` if the given batch was constrained by a limit."}}}}}},"400":{"description":"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.","$ref":"#/components/responses/ResponseError"},"402":{"description":"Error 234: the batch or file could not be parsed.","$ref":"#/components/responses/ResponseError"},"default":{"$ref":"#/components/responses/ResponseError"}}}}}} ``` #### Errors These errors come in addition to the [general error codes](/docs/navixy-api/general/errors.md#error-codes): * 234 - Invalid data format. *** *Required sub-user rights:* `zone_update`. ## Create geofence > 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. ```json {"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Geofences","description":"Geofences of all three shapes, their points, and spreadsheet and KML import and export. All resources under the /zone/ path."}],"servers":[{"url":"https://api.eu.navixy.com/v2","description":"Navixy production server on European platform"},{"url":"https://api.us.navixy.com/v2","description":"Navixy production server on American platform"},{"url":"https://api.me.navixy.com/v2","description":"Navixy production server on Middle East platform"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","description":"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.","name":"Authorization","in":"header"}},"schemas":{"Zone":{"type":"object","description":"A geofence: an area used to limit where a rule applies, and named after the address in reports when an event happens inside it.\n\n**One object, three shapes, selected by `type`.** A `circle` has `center` and `radius`. A `polygon` has `points`. A `sausage` has `points` and a `radius`, and covers everything within that distance of the polyline.","properties":{"id":{"type":"integer","description":"Geofence ID. Absent when creating."},"type":{"type":"string","description":"Which shape this geofence is, and therefore which of the fields below apply. **Cannot be changed** once the geofence exists.","enum":["circle","polygon","sausage"]},"label":{"type":"string","description":"Geofence label."},"address":{"type":"string","description":"Geofence address."},"color":{"type":"string","description":"Geofence colour, as a three-byte RGB hex value. Optional on create and update, defaulting to `27A9E3`."},"radius":{"type":"integer","description":"Radius in metres. **For `circle` it is the circle radius; for `sausage` it is the distance from the polyline. A `polygon` has no radius.**"},"center":{"type":"object","description":"Centre of the circle. **`circle` only.**","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."}}},"points":{"type":"array","description":"The geofence points. **`polygon` and `sausage` only**, and returned only when the operation was asked for them. On create they go in a separate `points` parameter instead.","items":{"$ref":"#/components/schemas/ZonePoint"}},"bounds":{"type":"object","description":"North-west and south-east corners of the axis-aligned minimum bounding box.","properties":{"nw":{"type":"object","description":"North-west corner.","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."}}},"se":{"type":"object","description":"South-east corner.","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."}}}}},"tags":{"type":"array","description":"IDs of tags applied to the geofence.","items":{"type":"integer"}}}},"ZonePoint":{"type":"object","description":"One point of a polygon or sausage geofence. A circle geofence has no points.","properties":{"lat":{"type":"number","description":"Point latitude."},"lng":{"type":"number","description":"Point longitude."},"node":{"type":"boolean","description":"`true` when this point is a route node."}}}},"responses":{"ResponseError":{"description":"Error response object","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always false."},"status":{"type":"object","description":"Error status. Present only when an error occurred.","properties":{"code":{"type":"integer","description":"An error code in this API, not an HTTP code."},"description":{"type":"string","description":"An error description."}}},"errors":{"type":"array","description":"Per-parameter detail, returned with validation failures such as error code 7. A parameter name here may be an internal field name rather than the documented parameter name.","items":{"type":"object","properties":{"parameter":{"type":"string","description":"Name of the parameter that failed validation."},"error":{"type":"string","description":"What was wrong with it."}}}}}}}}}}},"paths":{"/zone/create":{"post":{"tags":["Geofences"],"summary":"Create geofence","description":"Create a geofence, and return its ID.\n\nPass the zone object without `id`. `color` is optional and defaults to `27A9E3`.\n\nPoints 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.\n\nRequires the `zone_update` right.","operationId":"zoneCreate","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"zone":{"allOf":[{"$ref":"#/components/schemas/Zone"}],"description":"The geofence to create, without `id`."},"points":{"type":"array","description":"Points for a polygon or sausage. **Omit for a circle.** 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.","items":{"$ref":"#/components/schemas/ZonePoint"}}},"required":["zone"]}}}},"responses":{"200":{"description":"The created geofence","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true},"id":{"type":"integer","description":"ID of the new geofence."}}}}}},"400":{"description":"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.","$ref":"#/components/responses/ResponseError"},"402":{"description":"Error 268: the user's quota for geofences is exhausted.","$ref":"#/components/responses/ResponseError"},"403":{"description":"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.","$ref":"#/components/responses/ResponseError"},"default":{"$ref":"#/components/responses/ResponseError"}}}}}} ``` #### Errors These errors come in addition to the [general error codes](/docs/navixy-api/general/errors.md#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 `points` were 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 geofences > 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. ```json {"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Geofences","description":"Geofences of all three shapes, their points, and spreadsheet and KML import and export. All resources under the /zone/ path."}],"servers":[{"url":"https://api.eu.navixy.com/v2","description":"Navixy production server on European platform"},{"url":"https://api.us.navixy.com/v2","description":"Navixy production server on American platform"},{"url":"https://api.me.navixy.com/v2","description":"Navixy production server on Middle East platform"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","description":"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.","name":"Authorization","in":"header"}},"responses":{"OK":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true}}}}}},"ResponseError":{"description":"Error response object","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always false."},"status":{"type":"object","description":"Error status. Present only when an error occurred.","properties":{"code":{"type":"integer","description":"An error code in this API, not an HTTP code."},"description":{"type":"string","description":"An error description."}}},"errors":{"type":"array","description":"Per-parameter detail, returned with validation failures such as error code 7. A parameter name here may be an internal field name rather than the documented parameter name.","items":{"type":"object","properties":{"parameter":{"type":"string","description":"Name of the parameter that failed validation."},"error":{"type":"string","description":"What was wrong with it."}}}}}}}}}}},"paths":{"/zone/delete":{"post":{"tags":["Geofences"],"summary":"Delete geofences","description":"Delete one geofence or several by ID.\n\n**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`.\n\n**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.\n\nRequires the `zone_update` right.\n\nAlso accepts GET with the same parameters as query-string values.","operationId":"zoneDelete","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"zone_id":{"type":"integer","description":"ID of a single geofence to delete. Use this or `zone_ids`, not both."},"zone_ids":{"type":"array","description":"IDs of geofences to delete. Use this or `zone_id`, not both.","items":{"type":"integer"}}}}}}},"responses":{"200":{"description":"Geofences deleted","$ref":"#/components/responses/OK"},"400":{"description":"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.","$ref":"#/components/responses/ResponseError"},"409":{"description":"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.","$ref":"#/components/responses/ResponseError"},"default":{"$ref":"#/components/responses/ResponseError"}}}}}} ``` #### Errors These errors come in addition to the [general error codes](/docs/navixy-api/general/errors.md#error-codes): * 201 - Not found in the database. * 203 - Delete entity associated with. The response body names what still references the geofence: ```json { "success": false, "status": { "code": 203, "description": "Delete entity associated with" }, "entities": [ { "type": "rules", "ids": [12345, 23456] } ] } ``` `ids` is an int array holding the IDs of the rules that use the geofence. *** ## List geofences > 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. ```json {"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Geofences","description":"Geofences of all three shapes, their points, and spreadsheet and KML import and export. All resources under the /zone/ path."}],"servers":[{"url":"https://api.eu.navixy.com/v2","description":"Navixy production server on European platform"},{"url":"https://api.us.navixy.com/v2","description":"Navixy production server on American platform"},{"url":"https://api.me.navixy.com/v2","description":"Navixy production server on Middle East platform"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","description":"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.","name":"Authorization","in":"header"}},"schemas":{"Zone":{"type":"object","description":"A geofence: an area used to limit where a rule applies, and named after the address in reports when an event happens inside it.\n\n**One object, three shapes, selected by `type`.** A `circle` has `center` and `radius`. A `polygon` has `points`. A `sausage` has `points` and a `radius`, and covers everything within that distance of the polyline.","properties":{"id":{"type":"integer","description":"Geofence ID. Absent when creating."},"type":{"type":"string","description":"Which shape this geofence is, and therefore which of the fields below apply. **Cannot be changed** once the geofence exists.","enum":["circle","polygon","sausage"]},"label":{"type":"string","description":"Geofence label."},"address":{"type":"string","description":"Geofence address."},"color":{"type":"string","description":"Geofence colour, as a three-byte RGB hex value. Optional on create and update, defaulting to `27A9E3`."},"radius":{"type":"integer","description":"Radius in metres. **For `circle` it is the circle radius; for `sausage` it is the distance from the polyline. A `polygon` has no radius.**"},"center":{"type":"object","description":"Centre of the circle. **`circle` only.**","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."}}},"points":{"type":"array","description":"The geofence points. **`polygon` and `sausage` only**, and returned only when the operation was asked for them. On create they go in a separate `points` parameter instead.","items":{"$ref":"#/components/schemas/ZonePoint"}},"bounds":{"type":"object","description":"North-west and south-east corners of the axis-aligned minimum bounding box.","properties":{"nw":{"type":"object","description":"North-west corner.","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."}}},"se":{"type":"object","description":"South-east corner.","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."}}}}},"tags":{"type":"array","description":"IDs of tags applied to the geofence.","items":{"type":"integer"}}}},"ZonePoint":{"type":"object","description":"One point of a polygon or sausage geofence. A circle geofence has no points.","properties":{"lat":{"type":"number","description":"Point latitude."},"lng":{"type":"number","description":"Point longitude."},"node":{"type":"boolean","description":"`true` when this point is a route node."}}}},"responses":{"ResponseError":{"description":"Error response object","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always false."},"status":{"type":"object","description":"Error status. Present only when an error occurred.","properties":{"code":{"type":"integer","description":"An error code in this API, not an HTTP code."},"description":{"type":"string","description":"An error description."}}},"errors":{"type":"array","description":"Per-parameter detail, returned with validation failures such as error code 7. A parameter name here may be an internal field name rather than the documented parameter name.","items":{"type":"object","properties":{"parameter":{"type":"string","description":"Name of the parameter that failed validation."},"error":{"type":"string","description":"What was wrong with it."}}}}}}}}}}},"paths":{"/zone/list":{"post":{"tags":["Geofences"],"summary":"List geofences","description":"List the geofences of the current user, with filtering and pagination.\n\nPoints are left out unless `with_points` is set, because a polygon or sausage can carry hundreds of them.\n\nCallable with an empty body. Also accepts GET with the same parameters as query-string values.","operationId":"zoneList","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"filter":{"type":"string","description":"Optional. Filter over geofence label and description."},"tag_ids":{"type":"array","description":"Optional. Tag IDs. A geofence must carry **all** the tags in the list to be returned.","items":{"type":"integer"}},"offset":{"type":"integer","description":"Optional. Offset into the found geofences, for pagination.","minimum":0},"limit":{"type":"integer","description":"Optional. Number of geofences to return."},"with_points":{"type":"boolean","description":"Optional. Default `false`. Include each geofence's points."}}}}}},"responses":{"200":{"description":"Matching geofences","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true},"list":{"type":"array","items":{"$ref":"#/components/schemas/Zone"}},"count":{"type":"integer","description":"Total number of geofences matching the filter, ignoring pagination. `ZoneListAction` returns a `ListWithCountResponse`, so this is always present."}}}}}},"400":{"description":"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.","$ref":"#/components/responses/ResponseError"},"default":{"$ref":"#/components/responses/ResponseError"}}}}}} ``` *** ## Read geofence > 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. ```json {"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Geofences","description":"Geofences of all three shapes, their points, and spreadsheet and KML import and export. All resources under the /zone/ path."}],"servers":[{"url":"https://api.eu.navixy.com/v2","description":"Navixy production server on European platform"},{"url":"https://api.us.navixy.com/v2","description":"Navixy production server on American platform"},{"url":"https://api.me.navixy.com/v2","description":"Navixy production server on Middle East platform"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","description":"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.","name":"Authorization","in":"header"}},"schemas":{"Zone":{"type":"object","description":"A geofence: an area used to limit where a rule applies, and named after the address in reports when an event happens inside it.\n\n**One object, three shapes, selected by `type`.** A `circle` has `center` and `radius`. A `polygon` has `points`. A `sausage` has `points` and a `radius`, and covers everything within that distance of the polyline.","properties":{"id":{"type":"integer","description":"Geofence ID. Absent when creating."},"type":{"type":"string","description":"Which shape this geofence is, and therefore which of the fields below apply. **Cannot be changed** once the geofence exists.","enum":["circle","polygon","sausage"]},"label":{"type":"string","description":"Geofence label."},"address":{"type":"string","description":"Geofence address."},"color":{"type":"string","description":"Geofence colour, as a three-byte RGB hex value. Optional on create and update, defaulting to `27A9E3`."},"radius":{"type":"integer","description":"Radius in metres. **For `circle` it is the circle radius; for `sausage` it is the distance from the polyline. A `polygon` has no radius.**"},"center":{"type":"object","description":"Centre of the circle. **`circle` only.**","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."}}},"points":{"type":"array","description":"The geofence points. **`polygon` and `sausage` only**, and returned only when the operation was asked for them. On create they go in a separate `points` parameter instead.","items":{"$ref":"#/components/schemas/ZonePoint"}},"bounds":{"type":"object","description":"North-west and south-east corners of the axis-aligned minimum bounding box.","properties":{"nw":{"type":"object","description":"North-west corner.","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."}}},"se":{"type":"object","description":"South-east corner.","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."}}}}},"tags":{"type":"array","description":"IDs of tags applied to the geofence.","items":{"type":"integer"}}}},"ZonePoint":{"type":"object","description":"One point of a polygon or sausage geofence. A circle geofence has no points.","properties":{"lat":{"type":"number","description":"Point latitude."},"lng":{"type":"number","description":"Point longitude."},"node":{"type":"boolean","description":"`true` when this point is a route node."}}}},"responses":{"ResponseError":{"description":"Error response object","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always false."},"status":{"type":"object","description":"Error status. Present only when an error occurred.","properties":{"code":{"type":"integer","description":"An error code in this API, not an HTTP code."},"description":{"type":"string","description":"An error description."}}},"errors":{"type":"array","description":"Per-parameter detail, returned with validation failures such as error code 7. A parameter name here may be an internal field name rather than the documented parameter name.","items":{"type":"object","properties":{"parameter":{"type":"string","description":"Name of the parameter that failed validation."},"error":{"type":"string","description":"What was wrong with it."}}}}}}}}}}},"paths":{"/zone/read":{"post":{"tags":["Geofences"],"summary":"Read geofence","description":"Return one geofence by ID.\n\nPoints are left out unless `with_points` is set.\n\nAlso accepts GET with the same parameters as query-string values.","operationId":"zoneRead","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"zone_id":{"type":"integer","description":"ID of the geofence.","minimum":1},"with_points":{"type":"boolean","description":"Optional. Default `false`. Include the geofence's points."}},"required":["zone_id"]}}}},"responses":{"200":{"description":"The geofence","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true},"value":{"$ref":"#/components/schemas/Zone"}}}}}},"400":{"description":"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.","$ref":"#/components/responses/ResponseError"},"default":{"$ref":"#/components/responses/ResponseError"}}}}}} ``` *** ## Search geofences by location > Return the ID and name of every geofence whose area contains the given coordinates.\ > \ > The place equivalent is \`place/search\_location\`. ```json {"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Geofences","description":"Geofences of all three shapes, their points, and spreadsheet and KML import and export. All resources under the /zone/ path."}],"servers":[{"url":"https://api.eu.navixy.com/v2","description":"Navixy production server on European platform"},{"url":"https://api.us.navixy.com/v2","description":"Navixy production server on American platform"},{"url":"https://api.me.navixy.com/v2","description":"Navixy production server on Middle East platform"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","description":"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.","name":"Authorization","in":"header"}},"responses":{"ResponseError":{"description":"Error response object","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always false."},"status":{"type":"object","description":"Error status. Present only when an error occurred.","properties":{"code":{"type":"integer","description":"An error code in this API, not an HTTP code."},"description":{"type":"string","description":"An error description."}}},"errors":{"type":"array","description":"Per-parameter detail, returned with validation failures such as error code 7. A parameter name here may be an internal field name rather than the documented parameter name.","items":{"type":"object","properties":{"parameter":{"type":"string","description":"Name of the parameter that failed validation."},"error":{"type":"string","description":"What was wrong with it."}}}}}}}}}}},"paths":{"/zone/search_location":{"post":{"tags":["Geofences"],"summary":"Search geofences by location","description":"Return the ID and name of every geofence whose area contains the given coordinates.\n\nThe place equivalent is `place/search_location`.","operationId":"zoneSearchLocation","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"location":{"type":"object","description":"The point to test.","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."}}}},"required":["location"]}}}},"responses":{"200":{"description":"Geofences containing the point","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true},"list":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"ID of a geofence containing the searched location."},"label":{"type":"string","description":"Name of that geofence."}}}}}}}}},"400":{"description":"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.","$ref":"#/components/responses/ResponseError"},"default":{"$ref":"#/components/responses/ResponseError"}}}}}} ``` *** A `points` array inside the `zone` object is applied with the rest of the update. [`zone/point/update`](/docs/navixy-api/user-api/resources/tracking/zone/zone_point.md#post-zone-point-update) does the same thing on its own. *Required sub-user rights:* `zone_update`. ## Update geofence > 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. ```json {"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Geofences","description":"Geofences of all three shapes, their points, and spreadsheet and KML import and export. All resources under the /zone/ path."}],"servers":[{"url":"https://api.eu.navixy.com/v2","description":"Navixy production server on European platform"},{"url":"https://api.us.navixy.com/v2","description":"Navixy production server on American platform"},{"url":"https://api.me.navixy.com/v2","description":"Navixy production server on Middle East platform"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","description":"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.","name":"Authorization","in":"header"}},"schemas":{"Zone":{"type":"object","description":"A geofence: an area used to limit where a rule applies, and named after the address in reports when an event happens inside it.\n\n**One object, three shapes, selected by `type`.** A `circle` has `center` and `radius`. A `polygon` has `points`. A `sausage` has `points` and a `radius`, and covers everything within that distance of the polyline.","properties":{"id":{"type":"integer","description":"Geofence ID. Absent when creating."},"type":{"type":"string","description":"Which shape this geofence is, and therefore which of the fields below apply. **Cannot be changed** once the geofence exists.","enum":["circle","polygon","sausage"]},"label":{"type":"string","description":"Geofence label."},"address":{"type":"string","description":"Geofence address."},"color":{"type":"string","description":"Geofence colour, as a three-byte RGB hex value. Optional on create and update, defaulting to `27A9E3`."},"radius":{"type":"integer","description":"Radius in metres. **For `circle` it is the circle radius; for `sausage` it is the distance from the polyline. A `polygon` has no radius.**"},"center":{"type":"object","description":"Centre of the circle. **`circle` only.**","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."}}},"points":{"type":"array","description":"The geofence points. **`polygon` and `sausage` only**, and returned only when the operation was asked for them. On create they go in a separate `points` parameter instead.","items":{"$ref":"#/components/schemas/ZonePoint"}},"bounds":{"type":"object","description":"North-west and south-east corners of the axis-aligned minimum bounding box.","properties":{"nw":{"type":"object","description":"North-west corner.","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."}}},"se":{"type":"object","description":"South-east corner.","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."}}}}},"tags":{"type":"array","description":"IDs of tags applied to the geofence.","items":{"type":"integer"}}}},"ZonePoint":{"type":"object","description":"One point of a polygon or sausage geofence. A circle geofence has no points.","properties":{"lat":{"type":"number","description":"Point latitude."},"lng":{"type":"number","description":"Point longitude."},"node":{"type":"boolean","description":"`true` when this point is a route node."}}}},"responses":{"OK":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true}}}}}},"ResponseError":{"description":"Error response object","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always false."},"status":{"type":"object","description":"Error status. Present only when an error occurred.","properties":{"code":{"type":"integer","description":"An error code in this API, not an HTTP code."},"description":{"type":"string","description":"An error description."}}},"errors":{"type":"array","description":"Per-parameter detail, returned with validation failures such as error code 7. A parameter name here may be an internal field name rather than the documented parameter name.","items":{"type":"object","properties":{"parameter":{"type":"string","description":"Name of the parameter that failed validation."},"error":{"type":"string","description":"What was wrong with it."}}}}}}}}}}},"paths":{"/zone/update":{"post":{"tags":["Geofences"],"summary":"Update geofence","description":"Update a geofence. Pass the zone object with its `id`.\n\n**The type cannot be changed.** A geofence stored as a circle cannot be submitted as a polygon, and trying returns error 231.\n\nFor 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.\n\nRequires the `zone_update` right.","operationId":"zoneUpdate","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"zone":{"allOf":[{"$ref":"#/components/schemas/Zone"}],"description":"The geofence to update, including its `id`. Its `type` must match what is stored."}},"required":["zone"]}}}},"responses":{"200":{"description":"Geofence updated","$ref":"#/components/responses/OK"},"400":{"description":"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.","$ref":"#/components/responses/ResponseError"},"409":{"description":"Error 231: the submitted type differs from the stored type.","$ref":"#/components/responses/ResponseError"},"default":{"$ref":"#/components/responses/ResponseError"}}}}}} ``` #### Errors These errors come in addition to the [general error codes](/docs/navixy-api/general/errors.md#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: ```xml Points 300 named point 44.7463912723,41.7096716534 ``` A `Placemark` name becomes the geofence name, and the `Folder` and `Document` hierarchy around it is preserved. *Required sub-user rights:* `zone_update`. ## Upload geofences > 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. ```json {"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Geofences","description":"Geofences of all three shapes, their points, and spreadsheet and KML import and export. All resources under the /zone/ path."}],"servers":[{"url":"https://api.eu.navixy.com/v2","description":"Navixy production server on European platform"},{"url":"https://api.us.navixy.com/v2","description":"Navixy production server on American platform"},{"url":"https://api.me.navixy.com/v2","description":"Navixy production server on Middle East platform"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","description":"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.","name":"Authorization","in":"header"}},"responses":{"ResponseError":{"description":"Error response object","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always false."},"status":{"type":"object","description":"Error status. Present only when an error occurred.","properties":{"code":{"type":"integer","description":"An error code in this API, not an HTTP code."},"description":{"type":"string","description":"An error description."}}},"errors":{"type":"array","description":"Per-parameter detail, returned with validation failures such as error code 7. A parameter name here may be an internal field name rather than the documented parameter name.","items":{"type":"object","properties":{"parameter":{"type":"string","description":"Name of the parameter that failed validation."},"error":{"type":"string","description":"What was wrong with it."}}}}}}}}}}},"paths":{"/zone/upload":{"post":{"tags":["Geofences"],"summary":"Upload geofences","description":"Import geofences from a KML file.\n\n**This is a multipart request**, not JSON: `multipart/form-data` with the KML in a part named `file`.\n\n**`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.\n\nA `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.\n\nRequires the `zone_update` right.","operationId":"zoneUpload","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","description":"The KML file of geofences.","format":"binary"},"default_radius":{"type":"integer","description":"Default radius in metres for a circle or route geofence. Minimum 20, default 150.","minimum":20},"dry_run":{"type":"boolean","description":"Default `true`. When `true`, return the geofences that would be created without creating them. When `false`, create them and return their IDs."},"redirect_target":{"type":"string","description":"Optional. URL to redirect to after the upload."}},"required":["file"]}}}},"responses":{"200":{"description":"The geofences that would be created, or the IDs of those created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true},"list":{"type":"array","description":"With `dry_run` true, the geofences ready to create. With `dry_run` false, the IDs of the geofences created.","items":{}}}}}}},"400":{"description":"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.","$ref":"#/components/responses/ResponseError"},"402":{"description":"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.","$ref":"#/components/responses/ResponseError"},"403":{"description":"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.","$ref":"#/components/responses/ResponseError"},"default":{"$ref":"#/components/responses/ResponseError"}}}}}} ``` #### Errors These errors come in addition to the [general error codes](/docs/navixy-api/general/errors.md#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 `file` part 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`: ```xml zones polygon_zone 1 44.7489290062,41.7201261755 44.7572878562,41.7208046390 44.7562364303,41.7190268459 circle_zone 1 300 44.7463912723,41.7096716534 sausage_zone 1 300 44.7288827746,41.7176609187 44.7340679137,41.7181063157 44.7384917427,41.7187820845 ``` ## Download geofences > 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. ```json {"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Geofences","description":"Geofences of all three shapes, their points, and spreadsheet and KML import and export. All resources under the /zone/ path."}],"servers":[{"url":"https://api.eu.navixy.com/v2","description":"Navixy production server on European platform"},{"url":"https://api.us.navixy.com/v2","description":"Navixy production server on American platform"},{"url":"https://api.me.navixy.com/v2","description":"Navixy production server on Middle East platform"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","description":"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.","name":"Authorization","in":"header"}},"responses":{"ResponseError":{"description":"Error response object","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always false."},"status":{"type":"object","description":"Error status. Present only when an error occurred.","properties":{"code":{"type":"integer","description":"An error code in this API, not an HTTP code."},"description":{"type":"string","description":"An error description."}}},"errors":{"type":"array","description":"Per-parameter detail, returned with validation failures such as error code 7. A parameter name here may be an internal field name rather than the documented parameter name.","items":{"type":"object","properties":{"parameter":{"type":"string","description":"Name of the parameter that failed validation."},"error":{"type":"string","description":"What was wrong with it."}}}}}}}}}}},"paths":{"/zone/download":{"post":{"tags":["Geofences"],"summary":"Download geofences","description":"Return geofences as a KML or KMZ file.\n\nThe response is the file itself, not a JSON envelope. Both parameters are optional, so an empty body downloads every available geofence as KML.","operationId":"zoneDownload","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"format":{"type":"string","description":"Optional. Default `kml`. File format.","enum":["kml","kmz"]},"zone_ids":{"type":"array","description":"Optional. Geofences to include. When null, every available geofence is downloaded.","items":{"type":"integer"}}}}}}},"responses":{"200":{"description":"The geofences as a KML or KMZ file","content":{"application/vnd.google-earth.kml+xml":{"schema":{"type":"string","format":"binary"}},"application/vnd.google-earth.kmz":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"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.","$ref":"#/components/responses/ResponseError"},"default":{"$ref":"#/components/responses/ResponseError"}}}}}} ``` ## More in this section #### Geofence import | Endpoint | Method | What it does | | ------------------------------------------------------------------------------------------------------------------------------ | ------ | ----------------------------- | | [`/zone/import/start`](/docs/navixy-api/user-api/resources/tracking/zone/import.md#post-zone-import-start) | POST | Start geofence import | | [`/zone/import/read`](/docs/navixy-api/user-api/resources/tracking/zone/import.md#post-zone-import-read) | POST | Read geofence import | | [`/zone/import/list`](/docs/navixy-api/user-api/resources/tracking/zone/import.md#post-zone-import-list) | POST | List geofence imports | | [`/zone/import/download_failed`](/docs/navixy-api/user-api/resources/tracking/zone/import.md#post-zone-import-download_failed) | POST | Download failed geofence rows | | [`/zone/import/finish`](/docs/navixy-api/user-api/resources/tracking/zone/import.md#post-zone-import-finish) | POST | Finish geofence import | #### Geofence point | Endpoint | Method | What it does | | -------------------------------------------------------------------------------------------------------------- | ------ | ---------------------- | | [`/zone/point/list`](/docs/navixy-api/user-api/resources/tracking/zone/zone_point.md#post-zone-point-list) | POST | List geofence points | | [`/zone/point/update`](/docs/navixy-api/user-api/resources/tracking/zone/zone_point.md#post-zone-point-update) | POST | Update geofence points | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://navixy.com/docs/navixy-api/user-api/resources/tracking/zone.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.