Geofence import
Create many circle geofences at once from a spreadsheet, through a background import process.
Geofence import creates many circle geofences at once from a spreadsheet. Only circles can be imported this way.
The import runs as a background process across five operations. Convert the spreadsheet first with data/spreadsheet/parse, which stores it as a tab-separated file and returns its name. Pass that name to zone/import/start as filename, follow the process with zone/import/read or zone/import/list, collect the rows that failed validation with zone/import/download_failed, and close the finished process with zone/import/finish.
Address and coordinates complete each other. A row that gives only an address gets its coordinates by geocoding, and a row that gives only coordinates gets its address by reverse geocoding. Tags that do not exist yet are created, within the user's quota for tags.
Import process object
API actions
API base path: /zone/import.
Operations that list no errors of their own return only the general error codes.
Required sub-user rights: zone_update.
Start the background process that imports circle geofences from a preloaded TSV file, and return the process ID. Only circles can be imported.
Create the file first with data/spreadsheet/parse, which converts a spreadsheet to TSV and returns its name as file_id. Pass that name here as filename.
Address and coordinates complete each other: given only an address the coordinates come from geocoding, and given only coordinates the address comes from reverse geocoding.
Tags that do not exist yet are created automatically, within the user's tag quota.
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.
Name of the server-side TSV file, as returned by data/spreadsheet/parse in its file_id. Must not be empty.
What each column of the file holds, in order. Must not be empty. Accepted names are label, address, lat, lng, radius which defaults to 100, tags, and undefined for a column whose meaning is not known.
Optional. Display labels for the columns. Must be the same length as headers.
The started import
true if request finished successfully.
trueID of the created import process.
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 233: the preloaded file was not found. Error 234: the file is not a TSV.
Error 247: an identical import already exists for the same file.
Error 15: too many requests, when too many imports are already in progress.
Error response object
POST /v2/zone/import/start HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 62
{
"filename": "text",
"headers": [
"text"
],
"user_headers": [
"text"
]
}{
"success": true,
"id": 1
}Errors
These errors come in addition to the general error codes:
15 - Too many requests, when too many imports are already in progress.
233 - No data file, when the preloaded file is not found.
234 - Invalid data format, when the file is not a TSV.
247 - Entity already exists, when another import already uses the same file.
Return one geofence import process by ID, including its progress.
The import process object is the same shape every import family returns, differing only in type, which is zone here.
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 import process.
The import process
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/import/read HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 16
{
"process_id": 1
}{
"success": true,
"value": {
"id": 1,
"user_id": 1,
"subuser_id": 1,
"created": "text",
"type": "place",
"params": {
"headers": [
"text"
],
"user_headers": [
"text"
]
},
"filename": "text",
"status": "created",
"status_change_date": "text",
"progress": {
"imported": 1,
"failed": 1,
"percent": null,
"processed_lines": 1,
"warnings": [
{
"line": 1,
"message": "text"
}
],
"errors": [
{
"line": 1,
"message": "text"
}
]
}
}
}Errors
These errors come in addition to the general error codes:
201 - Not found in the database, when the import process is not found.
List the current user's unfinished geofence import processes.
Callable with an empty body.
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.
Unfinished import processes
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/import/list HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Accept: */*
{
"success": true,
"list": [
{
"id": 1,
"user_id": 1,
"subuser_id": 1,
"created": "text",
"type": "place",
"params": {
"headers": [
"text"
],
"user_headers": [
"text"
]
},
"filename": "text",
"status": "created",
"status_change_date": "text",
"progress": {
"imported": 1,
"failed": 1,
"percent": null,
"processed_lines": 1,
"warnings": [
{
"line": 1,
"message": "text"
}
],
"errors": [
{
"line": 1,
"message": "text"
}
]
}
}
]
}Return a file of the rows that failed validation, so they can be corrected and imported again.
The response is the file itself, not a JSON envelope.
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 import process.
The failed rows as a 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 204: the file of failed rows was not found.
Error response object
POST /v2/zone/import/download_failed HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 16
{
"process_id": 1
}binaryErrors
These errors come in addition to the general error codes:
201 - Not found in the database, when the import process is not found.
204 - Entity not found, when the file is not found.
Mark an import process as finished, which drops it out of zone/import/list.
Only a process that has stopped can be finished. One still running returns error 280.
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 import process.
Import marked finished
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/import/finish HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 16
{
"process_id": 1
}{
"success": true
}Errors
These errors come in addition to the general error codes:
201 - Not found in the database, when the import process is not found.
280 - Invalid import request state, when the import process is still running.
Last updated
Was this helpful?