Use Aliases, Metadata and Labels

Aliases

When integrating HERE Tracking into an external system, a tracker often has to be associated with an external ID in a way that is neither part of the reported state of the device or the desired state. For example, when attaching a tracker to a particular engine part or palette, assigning a human-readable name or synchronizing with an external asset management system.

These associations are known as 'Aliases'.

You can specify an alias type and an externalId to be stored alongside the device data. You can then retrieve a device record by referencing its alias.

Aliases are created by sending the type and externalId to HERE Tracking in the path of a PUT request:

curl -X PUT \
  https://tracking.api.here.com/aliases/v2/HERE-dummyTrackingId/testType/testExternalId

Once created, you can retrieve the details of a device using its alias type and externalId:

curl -X GET
  https://tracking.api.here.com/aliases/v2/trackingId?type=testType&externalId=testExternalId
{
  "trackingId": "HERE-dummyTrackingId"
}

Metadata

It can also be useful to store more data about a device or a geofence that isn't directly related to the identity or telemetry of the device. The icon to be displayed on a web interface, for instance, or detailed notes about a particular geofence. For this, we can use the Metadata service.

To store metadata about a device, send an arbitrary JSON object:

curl -X PUT \
  https://tracking.api.here.com/metadata/v2/devices/{trackingId} \
  -H 'Authorization: Bearer {userToken}' \
  -H 'Content-Type: application/json' \
  -d '{
    "deviceIcon": "car-icon.png"
}'

Metadata can be associated with geofences the same way but on a different path:

curl -X PUT \
  https://tracking.api.here.com/metadata/v2/geofences/{geofenceId} \
  -H 'Authorization: Bearer {userToken}' \
  -H 'Content-Type: application/json' \
  -d '{
    "geofenceIcon": "office-icon.png"
}'

Labels

A label is a key-value pair that can be associated to HERE Tracking resources listed as below,

  • device
  • geofence
  • sensor
  • rule
  • location
  • shipment

For example, if we need to group devices into different groups, we can associate devices with "group" labels, where the label value is the group name.

Labels are created by sending the resource type, resource ID and a label's key-value pair to HERE Tracking in the path of a PUT request. The example below is creating a device type label, and label key is "group" and value is "group-01".

curl -X PUT \
  https://tracking.api.here.com/labels/v4/device/HERE-dummyTrackingId/group/group-01 \
  -H 'Authorization: Bearer {userToken}' \
  -H 'Content-Type: application/json'

All labels associated with a specific type resource can be fetched via an endpoint containing this resource type:

curl -X GET \
  https://tracking.api.here.com/labels/v4/device \
  -H 'Authorization: Bearer {userToken}' \
  -H 'Content-Type: application/json'
{
 "limit":100,
 "count":1,
 "items":[{
  "resourceId":"HERE-dummyTrackingId",
  "resourceType":"device",
  "labels":{
      "group":["group-01"]
  }
 }]
}

The labels associated with a specific resource can be fetched via an endpoint containing this resource type and ID:

curl -X GET \
  https://tracking.api.here.com/labels/v4/device/HERE-dummyTrackingId \
  -H 'Authorization: Bearer {userToken}' \
  -H 'Content-Type: application/json'
{
  "resourceId":"HERE-dummyTrackingId",
  "resourceType":"device",
  "labels":
  {
    "group":["group-01"],
    "priority":["high"]
  }
}

results matching ""

    No results matching ""