Geofence events

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://{tcHost}/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.

For more information, see Gets all geofences.

curl -X GET \
  'https://{tcHost}/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.

Associate geofence and a virtual device

For more information, see Associates a device to a geofence.

The externalId specified in the request URL is an id of a provisioned virtual device.

curl -X PUT \
  https://{tcHost}/associations/v3/{externalId}/geofences/{geofenceId}?appId=`appId` \
  -H 'authorization: Bearer {userToken}' \
  -H 'content-type: application/json'

Send telemetry

Send telemetry outside the geofence and then inside the geofence.

See getting started with sending data to the cloud.

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

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

📘
Note
The timestamp is the UNIX Epoch time in milliseconds.

See that an event was recorded

All geofence events are recorded.

This will return all the events for a virtual device identified by the externalId and the project appId:

curl -X GET \
  https://{tcHost}/events/v3/{externalId}?appId=`appId` \
  -H 'authorization: Bearer {userToken}' \
  -H 'content-type: application/json'

For more information, see Gets event history for a device or a shipment.