Geofence events

Create a geofence

Geofences can be circular (specified by a centre point and a radius), polygonal (an array of coordinates) or custom POI (Point Of Interest geofences).

To create a geofence, send a request to the geofences endpoint. If the user is a member of multiple projects, the target project ID needs to be specified in the projectId query parameter.

curl -X POST \
  'https://tracking.api.here.com/geofences/v2?projectId=`projectId`' \
  -H 'authorization: Bearer {userToken}' \
  -H 'content-type: application/json' \
  -d '{
  "type": "circle",
  "definition":  {
    "center": {
      "lat": 52.521749,
      "lng": 13.413175
    },
    "radius": 150
  }
}'

This will create a circular geofence and return the unique geofence ID. At this point, the geofence isn't associated with any device but it will be visible in the Asset Tracking web application.

curl -X GET \
  'https://tracking.api.here.com/geofences/v2?projectId=`projectId`' \
  -H 'authorization: Bearer {userToken}' \
  -H 'content-type: application/json'

This will return a list of geofences the user previously created.

Associate geofence and device

Once created, the geofence can be associated to a device sending its location data to the Tracking API. This will generate an event whenever the device transitions from outside to inside of the geofence or vice versa.

The trackingId is a Tracking ID of a device claimed by the user.

curl -X PUT \
  https://tracking.api.here.com/associations/v3/{trackingId}/geofences/{geofenceId} \
  -H 'authorization: Bearer {userToken}' \
  -H 'content-type: application/json'

Send telemetry

Send telemetry outside the geofence and then inside the geofence.

NOTE: The timestamp is the UNIX Epoch time in milliseconds.

curl -X POST \
  https://tracking.api.here.com/v2/ \
  -H 'authorization: Bearer {deviceToken}' \
  -H 'content-type: application/json' \
  -d '[{
      "timestamp": 1569300623000,
      "position": {
        "alt": 107,
        "accuracy": 13,
        "lat": 52.520806,
        "lng": 13.410514,
        "altaccuracy": 14
      }
}]'

curl -X POST \
  https://tracking.api.here.com/v2/ \
  -H 'authorization: Bearer {deviceToken}' \
  -H 'content-type: application/json' \
  -d '[{
      "timestamp": 1569300814000,
      "position": {
        "alt": 107,
        "accuracy": 10,
        "lat": 52.521880,
        "lng": 13.412724,
        "altaccuracy": 15
      }
}]'

You can confirm the location of the latest ingestions using the Asset Tracking web application. The scenario created here will look like

See that an event was recorded

All geofence events are recorded.

curl -X GET \
  https://tracking.api.here.com/events/v3/{trackingId} \
  -H 'authorization: Bearer {userToken}' \
  -H 'content-type: application/json'

This will return all the events for a device identified by the trackingId.