Place object and API calls to work with points of interest (POI).
"Places" are business-specific points of interest (POI) like shops, delivery points, warehouses, etc. - which are visited by user's employees. Place entities can be extended with custom fields to make them even more useful.
In case an event happened at the POI, in various reports name of the POI will be specified after the address.
If there's an employee assigned to a Mobile Tracker App (Android / iOS), and a POI has a custom field of type "responsible employee", such point of interest will be available in the mobile app to view. Thus, field employee/driver can view all points of interest assigned to him to visit them, etc.
Working with POIs requires several actions so we described them in our guides.
id - int. An ID of a POI.
icon_id - optional int. Can be 1 to 255. Can only be updated via .
avatar_file_name - optional string. Name of the avatar file. Can be null.
API path: /place.
Gets POI by ID.
201 - Not found in the database – if there is no POI with such ID.
Get POIs belonging to user.
count - int. Found POIs count.
types only.
Creates a new POI.
required sub-user rights: place_update.
cURL
id - int. An ID of the created POI.
268 - Over quota – if the user's quota for POIs exceeded.
Gets all POI IDs and names within which a specified coordinates are located inside.
cURL
id - int. Place ID that containing a searched location.
label - string. Place name.
Updates existing POI.
required sub-user rights: place_update.
cURL
201 - Not found in the database – if there is no POI with such ID.
Deletes POI with the specified ID.
required sub-user rights: place_update.
201 - Not found in the database – if there is no POI with such ID.
Converts batch of tab-delimited POIs and return list of checked POIs with errors.
Required sub-user rights: place_update.
If file_id is set – batch parameter will be ignored.
list - a list of <checked_place> objects.
errors - optional array of objects. Errors found during check.
tag_names - optional string array. Tag names of the POI.
234 - Invalid data format.
Upload POIs.
Required sub-user rights: place_update.
MUST be a POST multipart request (multipart/form-data), with one of the parts being a CSV file upload (with the name "file").
CSV column separator is ;, columns header required – label;address;lat;lng;radius;external_id;description.
233 - No data file – if file part is missing.
234 - Invalid data format.
247 - Entity already exists – if uploaded POI contains external_id and POI with this ID already exists and duplicate_policy=fail.
location - required information about place location.lat - required, float. The latitude.
lng - required, float. The longitude.
address - required, string, max length 255. The address of place.
radius - required, int, 1..300000. The radius of place in meters.
fields - optional object. A map, each key of which is a custom field ID as a string. See entity/fields
label - string. POI name.
description - optional string. POI description.
tags - optional int array. A list of tag_ids. Non-empty.
external_id - optional string. Max length 32.
ascending
Optional. If false – descending order.
boolean
limit
Optional. Limit.
int
offset
Optional. offset, default is 0.
int
tag_ids
Optional. Tag IDs assigned to the place. The places found must include all the tags from the list.
int array
default_radius
Optional. Radius for point in meters. Default is 100.
int
limit_exceeded - boolean. true if given batch constrained by a limit.
geocoder
Geocoder type.
string
redirect_target
Optional URL to redirect. If redirect_target passed return redirect to <redirect_target>?response=<urlencoded_response_json>.
string
place_id
ID of the POI.
int
place_ids
Optional. List of POI IDs.
int array
filter
Optional. Filter for all built-in and custom fields. If used with conditions, both filter and conditions must match for every returned POI.
string
conditions
Optional. Search conditions to apply to list. Array of search conditions, see Search conditions.
array of objects
order_by
Optional. Built-in or custom field according to which output should be sorted. Entity field name, e.g "label" (builtin) or "123" (field ID as string, see entity/.
string
place
A place object without id field.
JSON object
ignore_missing_fields
Optional (default is false). If true, POI can be created even without all required custom fields.
boolean
location
Location coordinates (see: data types description section section).
JSON object
place
A place object.
JSON object
place_id
ID of the POI to delete.
int
batch
Batch of tab-delimited POIs.
string
file_id
Preloaded file ID.
string
fields
Optional. Array of field names, default is ["label", "address", "lat", "lng", "radius", "description", "tags"].
string array
geocoder
Geocoder type.
string
file
A CSV file upload containing POIs data.
File upload
error_policy
ignore or fail.
string
duplicate_policy
skip or update or fail, belongs only to external_id duplicates.
string
default_radius
Optional, radius for point, meters, default is 100.
int
{
"id": 1,
"icon_id": 55,
"avatar_file_name": null,
"location": {
"lat": 52.366,
"lng": 4.895,
"address": "730 5th Ave, New York, NY 10019, Unites States",
"radius": 500
},
"fields": {
"131312": {
"type": "text",
"value": "I love text!"
}
},
"label": "Crown Building",
"description": "Here we buy our goods",
"tags": [ 1, 2 ],
"external_id": "1"
}curl -X POST 'https://api.eu.navixy.com/v2/place/read' \
-H 'Content-Type: application/json' \
-d '{"hash": "22eac1c27af4be7b9d04da2ce1af111b", "place_id": 122304}'https://api.eu.navixy.com/v2/place/read?hash=a6aa75587e5c59c32d347da438505fc3&place_id=122304{
"success": true,
"value": {
"id": 1,
"icon_id": 55,
"avatar_file_name": null,
"location": {
"lat": 40.773998,
"lng": -73.66003,
"address": "730 5th Ave, New York, NY 10019, Unites States",
"radius": 50
},
"fields": {
"131312": {
"type": "text",
"value": "I love text!"
}
},
"label": "Crown Building",
"description": "Here we buy our goods",
"tags": [ 1, 2 ],
"external_id": "1"
}
}curl -X POST 'https://api.eu.navixy.com/v2/place/list' \
-H 'Content-Type: application/json' \
-d '{"hash": "22eac1c27af4be7b9d04da2ce1af111b"}'https://api.eu.navixy.com/v2/place/list?hash=a6aa75587e5c59c32d347da438505fc3{
"success": true,
"list": [
{
"id": 1,
"icon_id": 55,
"avatar_file_name": null,
"location": {
"lat": 40.773998,
"lng": -73.66003,
"address": "730 5th Ave, New York, NY 10019, Unites States",
"radius": 50
},
"fields": {
"131312": {
"type": "text",
"value": "I love text!"
}
},
"label": "Crown Building",
"description": "Here we buy our goods",
"tags": [ 1, 2 ],
"external_id": "1"
}
],
"count": 1
}curl -X POST 'https://api.eu.navixy.com/v2/place/create' \
-H 'Content-Type: application/json' \
-d '{"hash": "22eac1c27af4be7b9d04da2ce1af111b", "place": {"icon_id" : 55, "avatar_file_name": null, "location": {"lat": 40.773998, "lng": -73.66003, "address": "730 5th Ave, New York, NY 10019, Unites States", "radius": 50}, "fields": {"131312": {"type": "text", "value": "I love text!"}}, "label": "Crown Building", "description": "Here we buy our goods", "tags": [1, 2], "external_id": "1"}'{
"success": true,
"id": 111
}curl -X POST 'https://api.eu.navixy.com/v2/place/search_location' \
-H 'Content-Type: application/json' \
-d '{"hash": "22eac1c27af4be7b9d04da2ce1af111b", "location": {"lat": 34.178868, "lng": -118.599672}}'{
"list": [
{
"id": 1201,
"label": "place 1"
},
{
"id": 3574,
"label": "place 2"
}
],
"success": true
}curl -X POST 'https://api.eu.navixy.com/v2/place/update' \
-H 'Content-Type: application/json' \
-d '{"hash": "22eac1c27af4be7b9d04da2ce1af111b", "place": {"id": 111, "icon_id" : 55, "avatar_file_name": null, "location": {"lat": 40.773998, "lng": -73.66003, "address": "730 5th Ave, New York, NY 10019, Unites States", "radius": 50}, "fields": {"131312": {"type": "text", "value": "I love text!"}}, "label": "Crown Building", "description": "Here we buy our goods", "tags": [1, 2], "external_id": "1"}'{ "success": true }curl -X POST 'https://api.eu.navixy.com/v2/place/delete' \
-H 'Content-Type: application/json' \
-d '{"hash": "22eac1c27af4be7b9d04da2ce1af111b", "place_id": 122304}'https://api.eu.navixy.com/v2/place/delete?hash=a6aa75587e5c59c32d347da438505fc3&place_id=122304{ "success": true }{
"success": true,
"list": [
{
"id": 1,
"icon_id": 55,
"avatar_file_name": null,
"location": {
"lat": 40.773998,
"lng": -73.66003,
"address": "730 5th Ave, New York, NY 10019, Unites States",
"radius": 50
},
"fields": {
"131312": {
"type": "text",
"value": "I love text!"
}
},
"label": "Crown Building",
"description": "Here we buy our goods",
"tags": [ 1, 2 ],
"external_id": "1",
"errors": <array_of_objects>,
"tag_names": <array_of_strings>
}
],
"limit_exceeded": false
}{
"success": true,
"total": 1,
"errors": 0
}