Working with geofences¶

Geofences used in rules to limit rule area of activity. Also, geofence names shown in reports after the address, if an event happened inside the geofence.

This document describes CRUD actions for geofences. Note that geofence points handled separately because they are represented by big arrays of data.

Find instructions on working with geofences of different types here.

Entity description¶

zone is JSON object with one of types: sausage, circle or polygon.

circle:¶

{
  "id": 985472,
  "type": "circle",
  "label": "Zone name",
  "address": "Karlsplatz, 2",
  "color": "27A9E3",
  "radius": 150,
  "center": {
    "lat": 48.200940,
    "lng": 16.369856
  },
  "bounds": {
    "nw": {
      "lat": 48.202289,
      "lng": 16.367832
    },
    "se": {
      "lat": 48.199591,
      "lng": 16.371880
    }
  },
  "tags": [127, 15]
}

• id - int. Geofence ID.
• label - string. Geofence label.
• address - string. Geofence address.
• color - string. Geofence color in 3-byte RGB hex format.
• radius - int. Circle radius in meters.
• center - location object. Location of circle center.
• bounds - object. North-west and south-east coordinates of the axis-aligned minimum bounding box.
• tags - int array. Array of tag IDs.

polygon:¶

{
  "id": 124597,
  "type": "polygon",
  "label": "Geofence name",
  "address": "Karlsplatz, 2",
  "color": "27A9E3",
  "points": [<point>, ...],
  "bounds": {
    "nw": {
      "lat": 48.202289,
      "lng": 16.367832
    },
    "se": {
      "lat": 48.199591,
      "lng": 16.371880
    }
  },
  "tags": [1, 236]
}

• id - int. Geofence ID.
• label - string. Geofence label.
• address - string. Geofence address.
• color - string. Geofence color in 3-byte RGB hex format.
• points - optional array of objects. Geofence points
• bounds - object. North-west and south-east coordinates of the axis-aligned minimum bounding box that contains all points.
• tags - int array. Array of tag IDs.

sausage:¶

Represents all points within certain distance to the specified polyline.

{
  "id": 12345,
  "type": "sausage",
  "label": "Geofence name",
  "address": "Karlsplatz, 2",
  "color": "27A9E3",
  "radius": 150,
  "points": [<point>, ...],
  "bounds": {
    "nw": {
      "lat": 48.202289,
      "lng": 16.367832
    },
    "se": {
      "lat": 48.199591,
      "lng": 16.371880
    }
  },
  "tags": [289]
}

• id - int. Geofence ID.
• label - string. Geofence label.
• address - string. Geofence address.
• color - string. Geofence color in 3-byte RGB hex format.
• radius - int. Polyline radius in meters.
• points - optional array of objects. Geofence points
• bounds - object. North-west and south-east coordinates of the axis-aligned minimum bounding box that contains all points with a radius.
• tags - int array. Array of tag IDs.

API actions¶

API base path: /zone.

batch_convert¶

Convert batch of tab-delimited circle geofences and return list of checked geofences with errors.

required sub-user rights: zone_update.

Parameters¶

If 'file_id' is set – 'batch' parameter will be ignored.

For batch parameter: * address - required if coordinates are not specified. * lat - required if address is not specified. * lng - required if address is not specified.

Example¶

curl -X POST 'https://api.navixy.com/v2/zone/batch_convert' \
    -H 'Content-Type: application/json' \
    -d '{"hash": "22eac1c27af4be7b9d04da2ce1af111b", "batch": "Geofence for test Karlsplatz, 2"}'

Response¶

{
  "success": true,
  "list": [
    {
      "id": null,
      "type": "circle",
      "label": "Geofence name",
      "address": "Karlsplatz, 2",
      "color": "27A9E3",
      "radius": 100,
      "center": {
        "lat": 48.2009935,
        "lng": 16.3699642
      },
      "bounds": {
        "nw": {
          "lat": 48.202289,
          "lng": 16.367832
        },
        "se": {
          "lat": 48.199591,
          "lng": 16.371880
        }
      },
      "tags": []
    }
  ],
  "limit_exceeded": false
}

• id - int. Geofence ID.
• label - string. Geofence label.
• address - string. Geofence address.
• color - string. Geofence color in 3-byte RGB hex format.
• radius - int. Circle radius in meters.
• center - location object. Location of the circle center.
• bounds - object. North-west and south-east coordinates of the axis-aligned minimum bounding box.
• tags - int array. Array of tag IDs.
• limit_exceeded - boolean. true if given batch constrained by limit.

Response with errors object¶

{
  "success": true,
  "list": [
    {
      "id": null,
      "label": "Geofence name",
      "address": "incorrect address",
      "color": "27A9E3",
      "radius": 100,
      "center": {
        "lat": 0.0,
        "lng": 0.0
      },
      "errors": [
        {
          "parameter": "zone.center",
          "error": "Location should be correct with 'lat' and 'lng' not null"
        }
      ],
      "tags": []
    }
  ],
  "limit_exceeded": false
}

• errors - optional object. It appears if parameters are incorrect.
  • parameter - string. Parameter name.
  • error - string. Error description.

Errors¶

• 234 - Invalid data format.

create¶

Creates a new geofence.

required sub-user rights: zone_update.

Parameters¶

Example¶

curl -X POST 'https://api.navixy.com/v2/zone/create' \
    -H 'Content-Type: application/json' \
    -d '{"hash": "22eac1c27af4be7b9d04da2ce1af111b", "zone": {"label": "Circle geofence", "type": "circle", "center": {"lat": 61.49504550221769, "lng": 23.775476217269897}, "radius": 50, "tags": [179227], "color": "03A9F4", "address":"Address"}}'

Response¶

{
  "success": true,
  "id": 1234567
}

• id - int. An ID of the created geofence.

Errors¶

• 202 - Too many points in a geofence – max allowed count of points for a geofence is 500 for a polygon or 1024 for sausage.
• 230 - Not supported for this entity type – if "points" were specified, but geofence cannot have any points associated with it (e.g. if geofence is circle).
• 268 - Over quota – if the user's quota for geofences exceeded.
• 284 - Not enough points for the zone. The minimum number of points for polygon: 3; the minimum for sausage: 2.

delete¶

Deletes user's geofence by zone_id or array of zone_ids.

required sub-user rights: zone_update.

Parameters¶

• Use only one parameter zone_id or zone_ids.

Examples¶

curl -X POST 'https://api.navixy.com/v2/zone/delete' \
    -H 'Content-Type: application/json' \
    -d '{"hash": "22eac1c27af4be7b9d04da2ce1af111b", "zone_id": 1234567}'

https://api.navixy.com/v2/zone/delete?hash=a6aa75587e5c59c32d347da438505fc3&zone_id=1234567

Response¶

{
  "success": true
}

Errors¶

• 201 - Not found in the database.
• 203 - Delete entity associated with.

{
  "success": false,
  "status": {
    "code": 203,
    "description": "Delete entity associated with"
  },
  "entities": [
    {
      "type": "rules",
      "ids": [12345, 23456]
    }
  ]
}

• ids - int array. List IDs of the rules which uses the specified geofence.

list¶

Gets all user geofences.

Parameters¶

Examples¶

curl -X POST 'https://api.navixy.com/v2/zone/list' \
    -H 'Content-Type: application/json' \
    -d '{"hash": "22eac1c27af4be7b9d04da2ce1af111b"}'

https://api.navixy.com/v2/zone/list?hash=a6aa75587e5c59c32d347da438505fc3

Response¶

{
  "success": true,
  "list": [
    {
      "id": 12345,
      "type": "sausage",
      "label": "Zone name",
      "address": "Karlsplatz, 2",
      "color": "27A9E3",
      "radius": 150,
      "points": [<point>, ...],
      "tags": [289]
    }
  ]
}

• list - array of objects. Geofence objects with optional points field.

read¶

Gets geofence by specified ID.

Parameters¶

Examples¶

curl -X POST 'https://api.navixy.com/v2/zone/read' \
    -H 'Content-Type: application/json' \
    -d '{"hash": "22eac1c27af4be7b9d04da2ce1af111b", "zone_id": 12345}'

https://api.navixy.com/v2/zone/read?hash=a6aa75587e5c59c32d347da438505fc3&zone_id=12345

Response¶

{
  "success": true,
  "value": {
    "id": 12345,
    "type": "sausage",
    "label": "Zone name",
    "address": "Karlsplatz, 2",
    "color": "27A9E3",
    "radius": 150,
    "points": [<point>, ...],
    "tags": [289]
  }
}

• value - Geofence object with optional points field.

search_location¶

Gets all geofence IDs and names within which a specified coordinates are located inside.

Parameters¶

Example¶

curl -X POST 'https://api.navixy.com/v2/zone/search_location' \
    -H 'Content-Type: application/json' \
    -d '{"hash": "22eac1c27af4be7b9d04da2ce1af111b", "location": {"lat": 34.178868, "lng": -118.599672}}'

Response¶

{
  "list": [
    {
      "id": 18404,
      "label": "geofence 1"
    },
    {
      "id": 35284,
      "label": "geofence 2"
    }
  ],
  "success": true
}

• id - int. Geofence ID that containing a searched location.
• label - string. Geofence name.

update¶

Update geofence parameters for the specified geofence. Note that geofence must exist, must belong to the current user, and its type cannot be changed. E.g., if you already have a geofence with ID=1 which type is "circle", not possible to submit a geofence which type is "polygon".

required sub-user rights: zone_update.

Parameters¶

Example¶

curl -X POST 'https://api.navixy.com/v2/zone/update' \
    -H 'Content-Type: application/json' \
    -d '{"hash": "22eac1c27af4be7b9d04da2ce1af111b", "zone": {"id": 231512 "label": "Circle geofence", "type": "circle", "center": {"lat": 61.49504550221769, "lng": 23.775476217269897}, "radius": 50, "tags": [179227], "color": "03A9F4", "address":"Address"}}'

Response¶

{
  "success": true
}

Errors¶

• 201 - Not found in the database: if the geofence with specified ID cannot be found or belongs to another user.
• 231 - Entity type mismatch: if the type of submitted geofence differs from the type of geofence currently stored in the database.

upload¶

Import geofences from a KML file.

required sub-user rights: zone_update.

MUST be a POST multipart request (multipart/form-data), with one of the parts being a KML file upload (with the name "file").

Parameters¶

Responses¶

if dry_run=true:

{
  "success": true,
  "list": [
    {
      "id": null,
      "label": "Simple line 1",
      "address": "",
      "color": "27A9E3",
      "points": [
        {
          "lat": 37.818844,
          "lng": -122.366278,
          "node": true
        },
        {
          "lat": 37.819267,
          "lng": -122.365248,
          "node": false
        },
        {
          "lat": 37.819861,
          "lng": -122.36564,
          "node": false
        },
        {
          "lat": 37.819429,
          "lng": -122.366669,
          "node": true
        }
      ],
      "radius": 150,
      "type": "sausage"
    }
  ]
}

if dry_run=false:

{
  "success": true,
  "list": [1, 2]
}

Errors¶

• 202 - Too many points in a geofence – max allowed count of points for a geofence is 500 for a polygon or 1024 for sausage.
• 233 - No data file – if file part is missing.
• 234 - Invalid data format.
• 268 - Over quota – if the user's quota for geofences exceeded.
• 284 - Not enough points for the zone. The minimum number of points for polygon: 3; the minimum for sausage: 2.

From Placemark with Point geometry will be created circle geofence with a radius=default_radius.

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
    <Document>
        <name>Points</name>
        <Placemark>
            <name>named point</name>
            <Point>
                <coordinates>
                    -122.366278,37.818844,30
                </coordinates>
            </Point>
        </Placemark>
    </Document>
</kml>

From Placemark with LineString geometry will be created route geofence with a radius=default_radius.

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
    <Document>
        <name>Simple line</name>
        <Placemark>
            <LineString>
                <coordinates>
                    -122.366278,37.818844,30
                    -122.365248,37.819267,30
                    -122.365640,37.819861,30
                    -122.366669,37.819429,30
                </coordinates>
            </LineString>
        </Placemark>
    </Document>
</kml>

From Placemark with Polygon geometry will be created polygon geofence. Polygons with holes are not supported. In that case, only the outer boundary will be imported and the inner boundary, holes, ignored.

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
    <Document>
        <name>Simple polygon</name>
        <Placemark>
            <name>hollow box</name>
            <Polygon>
                <outerBoundaryIs>
                    <LinearRing>
                        <coordinates>
                            -122.366278,37.818844,30
                            -122.365248,37.819267,30
                            -122.365640,37.819861,30
                            -122.366669,37.819429,30
                            -122.366278,37.818844,30
                        </coordinates>
                    </LinearRing>
                </outerBoundaryIs>
            </Polygon>
        </Placemark>
    </Document>
</kml>

From Placemark with MultiGeometry geometry will be created several geofences. If Placemark.name defined it will be used as geofence name with respect of hierarchy of Folder and Document.