Use Aliases, Metadata and Labels

📘

Note

The alias API endpoint is deprecated.

When integrating the Tracking backend with an external system, a tracker device often needs to be associated with an external system ID. It can be, for example, an external management system asset ID or a human-readable name.

The HERE Tracking API allows associating arbitrary type-externalId pairs with a trackingId. 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.

In the examples requests below the alias type is testType and externalId is testExternalId. The trackingId is a Tracking ID of a virtual device claimed by the user.

Aliases are created via the aliases endpoint:

curl -X PUT \
  https://{tcHost}/aliases/v2/{trackingId}/testType/testExternalId

This creates an alias. Once the alias is created, you can retrieve the details of the device using its alias:

curl -X GET
  https://{tcHost}/aliases/v2/{trackingId}?type=testType&externalId=testExternalId

{
  "trackingId": "HERE-dummyTrackingId"
}

This returns the device trackingId.

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 to the metadata endpoint:

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

Metadata can be associated with geofences in a similar way:

curl -X PUT \
  https://{tcHost}/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 with the following resource types:

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

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

Labels are created by specifying a resource type, a resource ID and a label key-value pair in the path of the PUT request of the labels endpoint. The example below is creating a device label, where the label key is group and the label value is group-01.

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

curl -X PUT \
  https://{tcHost}/labels/v4/device/{trackingId}/{key}/{value} \
  -H 'Authorization: Bearer {userToken}' \
  -H 'Content-Type: application/json'

All labels associated with a specific resource type can be fetched via the labels endpoint containing the resource type in the path. If the user is a member of multiple projects, the target project ID needs to be specified in the projectId query parameter.

curl -X GET \
  https://{tcHost}/labels/v4/device?projectId=`projectId` \
  -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 the labels endpoint containing the resource type and the resource ID:

curl -X GET \
  https://{tcHost}/labels/v4/device/{trackingId} \
  -H 'Authorization: Bearer {userToken}' \
  -H 'Content-Type: application/json'

{
  "resourceId":"HERE-dummyTrackingId",
  "resourceType":"device",
  "labels":
  {
    "group":["group-01"],
    "priority":["high"]
  }
}