Process sensor data

The HERE Tracking API supports different types of sensors such as battery, temperature, acceleration, and tamper sensors. In this example, we create a "My battery level" rule to notify the owner when the battery level of a device goes below 20%.

To create a sensor rule, send a request to the sensors 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}/sensors/v3?projectId=`projectId`' \
  -H 'authorization: Bearer {userToken}' \
  -H 'content-type: application/json' \
  -d '{
  "type": "battery",
  "range":  {
    "begin": 20,
    "end": 80
  },
  "name": "My battery level"
}'

This will create a battery rule and return the unique rule ID. At this point, the rule isn't associated with any device.

This will return a list of sensor rules the user previously created:

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

For more information, see Gets all sensor rules.

Associate rule and device

Once created, the sensor rule can be associated to a device, which is sending its sensor data to the Tracking API. This will generate an event whenever the reported device battery level goes in or out of range defined by the rule.

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

curl -X PUT \
  https://{tcHost}/associations/v3/{trackingId}/sensors/{ruleId} \
  -H 'authorization: Bearer {userToken}' \
  -H 'content-type: application/json'

Send telemetry

Send telemetry, including battery information, within the defined range and then below the range. 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": [
    {
      "timestamp": 1569300623010,
      "position": {
        "alt": 107,
        "accuracy": 13,
        "lat": 52.520806,
        "lng": 13.410514,
        "altaccuracy": 14
      },
      "system": {
        "reportedSensorData": {
          "batteryLevel": 21
        }
      }      
    }
  ]
}'

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

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

See that an event was recorded

All sensor events are recorded. You will see two different events: an event "in range" triggered by the first telemetry ingestion, and an event "below range" by the second one. Events are generated whenever the reported sensor state crosses the rule upper or lower threshold.

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.