Ctrlk
Log inGet startedAsk Navixy AI
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Places (POI)

Business locations that employees visit, called points of interest in the interface and places in the API.

A place is a location the business cares about and employees visit: a shop, a delivery point, a warehouse.

Places and points of interest are the same thing. The Navixy interface, the user documentation, and the guides in this section call them points of interest, or POIs. The API calls them places at every level: the path is /place, the object is Place, and anything referring to one does so through place_id.

This page uses "place" throughout, because that is what the API says. Reading POI wherever it appears elsewhere loses nothing.

Places do two things beyond sitting on a map. An event that happens inside one is labelled with the place name after the address in reports, and a place can be extended with custom fields so it carries whatever else the business needs.

One custom field type changes what field staff see. When a place carries a responsible-employee field, and that employee is assigned to a device running the Mobile Tracker App, for Android or iOS, the place appears in the app for them. That is how a driver sees the places they are expected to visit.

For a walkthrough, see how to manage POIs.

Place object

Custom field values are keyed by custom field ID as a string. See entity/fields. The avatar fields icon_id and avatar_file_name are set through avatar/assign and avatar/upload, not here.

API actions

API base path: /place.

Operations that list no errors of their own return only the general error codes.

Read place

post
/place/read

Return one point of interest by ID.

Also accepts GET with the same parameters as query-string values.

Authorizations
AuthorizationstringRequired

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.

Body
place_idinteger · min: 1Required

ID of the POI.

Responses
200

The POI

application/json
successbooleanRead-onlyOptional

true if request finished successfully.

Example: true
post/place/read
POST /v2/place/read HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 14

{
  "place_id": 1
}
{
  "success": true,
  "value": {
    "id": 1,
    "icon_id": null,
    "avatar_file_name": null,
    "location": {
      "lat": 1,
      "lng": 1,
      "address": "text",
      "radius": 1
    },
    "fields": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "label": "text",
    "description": null,
    "tags": [
      1
    ],
    "external_id": null,
    "files": [
      {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    ]
  }
}

Errors

These errors come in addition to the general error codes:

  • 201 - Not found in the database, when no place has the given ID.

The conditions parameter takes search conditions, and order_by takes either a built-in field name or a custom field ID as a string, see entity.

List places

post
/place/list

List the points of interest of the current user, with filtering, sorting and pagination.

Callable with an empty body. Also accepts GET with the same parameters as query-string values.

Authorizations
AuthorizationstringRequired

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.

Body
place_idsinteger[]Optional

Optional. Return only these POIs.

filterstringOptional

Optional. Filter over all built-in and custom fields. Used together with conditions: both must match for a POI to be returned.

order_bystringOptional

Optional. Field to sort by. Either a built-in name such as label, or a custom field ID as a string such as "123".

ascendingbooleanOptional

Optional. Sort direction. false sorts descending.

limitintegerOptional

Optional. Number of POIs to return.

offsetintegerOptional

Optional. Default 0. Offset into the results, for pagination.

tag_idsinteger[]Optional

Optional. Tag IDs. A POI must carry all the tags in the list to be returned.

Responses
200

Matching POIs

application/json
successbooleanRead-onlyOptional

true if request finished successfully.

Example: true
countintegerOptional

Total number of POIs found, ignoring pagination.

post/place/list
POST /v2/place/list HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 157

{
  "place_ids": [
    1
  ],
  "filter": "text",
  "conditions": [
    {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  ],
  "order_by": "text",
  "ascending": true,
  "limit": 1,
  "offset": 1,
  "tag_ids": [
    1
  ]
}
{
  "success": true,
  "list": [
    {
      "id": 1,
      "icon_id": null,
      "avatar_file_name": null,
      "location": {
        "lat": 1,
        "lng": 1,
        "address": "text",
        "radius": 1
      },
      "fields": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "label": "text",
      "description": null,
      "tags": [
        1
      ],
      "external_id": null,
      "files": [
        {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      ]
    }
  ],
  "count": 1
}

Required sub-user rights: place_update.

Create place

post
/place/create

Create a point of interest, and return its ID.

icon_id cannot be set here: it is changed through place/avatar/assign.

Requires the place_update right.

Authorizations
AuthorizationstringRequired

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.

Body
ignore_missing_fieldsbooleanOptional

Optional. Default false. When true, the POI is created even if a required custom field is missing.

Responses
200

The created POI

application/json
successbooleanRead-onlyOptional

true if request finished successfully.

Example: true
idintegerOptional

ID of the new POI.

post/place/create
POST /v2/place/create HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 255

{
  "place": {
    "id": 1,
    "icon_id": null,
    "avatar_file_name": null,
    "location": {
      "lat": 1,
      "lng": 1,
      "address": "text",
      "radius": 1
    },
    "fields": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "label": "text",
    "description": null,
    "tags": [
      1
    ],
    "external_id": null
  },
  "ignore_missing_fields": true
}
{
  "success": true,
  "id": 1
}

Errors

These errors come in addition to the general error codes:

  • 268 - Over quota, when the user's quota for places is exceeded.

Search places by location

post
/place/search_location

Return the ID and name of every point of interest whose zone contains the given coordinates.

Only lat and lng are used, so no radius is needed on the request.

Authorizations
AuthorizationstringRequired

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.

Body
Responses
200

POIs containing the point

application/json
successbooleanRead-onlyOptional

true if request finished successfully.

Example: true
post/place/search_location
POST /v2/place/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"
    }
  ]
}

Errors

These errors come in addition to the general error codes:

  • 201 - Not found in the database, when no place has the given ID.

Required sub-user rights: place_update.

Update place

post
/place/update

Update a point of interest. Pass a full place object including its id.

The avatar cannot be changed here. Use place/avatar/assign for a preset icon, or place/avatar/upload for an image.

Requires the place_update right.

Authorizations
AuthorizationstringRequired

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.

Body
ignore_missing_fieldsbooleanOptional

Optional. Default false. When true, the POI is updated even if a required custom field is missing.

Responses
200

POI updated

application/json
successbooleanRead-onlyOptional

true if request finished successfully.

Example: true
post/place/update
POST /v2/place/update HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 255

{
  "place": {
    "id": 1,
    "icon_id": null,
    "avatar_file_name": null,
    "location": {
      "lat": 1,
      "lng": 1,
      "address": "text",
      "radius": 1
    },
    "fields": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "label": "text",
    "description": null,
    "tags": [
      1
    ],
    "external_id": null
  },
  "ignore_missing_fields": true
}
{
  "success": true
}

Errors

These errors come in addition to the general error codes:

  • 201 - Not found in the database, when no place has the given ID.

Required sub-user rights: place_update.

Delete place

post
/place/delete

Delete a point of interest by ID.

Also accepts GET with the same parameters as query-string values.

Requires the place_update right.

Authorizations
AuthorizationstringRequired

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.

Body
place_idinteger · min: 1Required

ID of the POI to delete.

Responses
200

POI deleted

application/json
successbooleanRead-onlyOptional

true if request finished successfully.

Example: true
post/place/delete
POST /v2/place/delete HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 14

{
  "place_id": 1
}
{
  "success": true
}

Errors

These errors come in addition to the general error codes:

  • 201 - Not found in the database, when no place has the given ID.

Required sub-user rights: place_update.

Convert place batch

post
/place/batch_convert

Parse a tab-delimited batch of points of interest 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".

Requires the place_update right.

Authorizations
AuthorizationstringRequired

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.

Body
batchstringOptional

Batch of tab-delimited POIs.

file_idstringOptional

Preloaded file ID. Takes precedence over batch.

fieldsstring[]Optional

Optional. Column names, in order. Defaults to ["label", "address", "lat", "lng", "radius", "description", "tags"].

geocoderstringOptional

Geocoder type to use for resolving addresses.

default_radiusintegerOptional

Optional. Default 100. Zone radius in metres for a row that gives no radius.

Responses
200

The checked batch

application/json
successbooleanRead-onlyOptional

true if request finished successfully.

Example: true
limit_exceededbooleanOptional

true if the given batch was constrained by a limit.

post/place/batch_convert
POST /v2/place/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,
      "icon_id": null,
      "avatar_file_name": null,
      "location": {
        "lat": 1,
        "lng": 1,
        "address": "text",
        "radius": 1
      },
      "fields": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "label": "text",
      "description": null,
      "tags": [
        1
      ],
      "external_id": null,
      "files": [
        {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      ],
      "errors": [
        {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      ],
      "tag_names": [
        "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: place_update.

Upload places

post
/place/upload

Create points of interest in bulk from a CSV file.

This is a multipart request, not JSON: multipart/form-data with the CSV in a part named file.

The CSV separator is a semicolon and a header row is required, naming label;address;lat;lng;radius;external_id;description.

If redirect_target is passed, the response is a redirect to that URL with response=<urlencoded response json> appended.

Requires the place_update right.

Authorizations
AuthorizationstringRequired

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.

Body
filestring · binaryRequired

The CSV file of POIs.

error_policystring · enumOptional

What to do with a row that fails validation.

Possible values:
duplicate_policystring · enumOptional

What to do when an uploaded POI carries an external_id that already exists. Applies to external_id duplicates only.

Possible values:
default_radiusintegerOptional

Optional. Default 100. Zone radius in metres for a row that gives no radius.

geocoderstringOptional

Geocoder type to use for resolving addresses.

redirect_targetstringOptional

Optional. URL to redirect to after the upload.

Responses
200

The upload result

application/json
successbooleanRead-onlyOptional

true if request finished successfully.

Example: true
totalintegerOptional

Number of POIs processed.

errorsintegerOptional

Number of rows that failed.

post/place/upload
POST /v2/place/upload HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Content-Type: multipart/form-data
Accept: */*
Content-Length: 129

{
  "file": "binary",
  "error_policy": "ignore",
  "duplicate_policy": "skip",
  "default_radius": 1,
  "geocoder": "text",
  "redirect_target": "text"
}
{
  "success": true,
  "total": 1,
  "errors": 1
}

Errors

These errors come in addition to the general error codes:

  • 233 - No data file, when the file part is missing.

  • 234 - Invalid data format.

  • 247 - Entity already exists, when an uploaded place carries an external_id that a place already uses and duplicate_policy is fail.

  • 268 - Over quota, when the user's quota for places is exceeded.

PreviousPlace import
NextTask

Last updated

Was this helpful?