HERE Tracking

Gets service version

Gets service health

Gets the current timestamp Returns the current server time in seconds since the UNIX epoch. The server time is used to check the validity of the OAuth 1.0 header of a device data ingestion request. Devices must synchronise with the server time to avoid a clock skew. > Note that in the data ingestion request the timestamp is specified in milliseconds.

Gets service version

Gets service health

Gets service version

Updates bulk upload job status Updates bulk upload status. In case current status is pending or ongoing, user can perform action `cancel`, which cancels the bulk upload processes of the job that are still in the pending state. In case current status is completed, failed or cancelled, user can perform action `acknowledged` which can be used to mark the job acknowledged.

Updates a shipment plan details Updates details of a shipment plan identified by the `shipmentPlanId`. This is a partial update, meaning that only the provided fields will be updated. If `ruleIds` field is specified, it will replace the existing rules currently associated with the shipment plan. ***Note***: `segments` cannot be edited through this API. Changing the order of the segments in a plan would cause shipments created from earlier versions of the plan diverge from a shipment instantiated from the new plan with different segment structure. Individual segments can still be updated via the `shipments/v4/plans/{shipmentPlanId}/{segmentPlanId}` endpoint.

Updates a segment plan details Updates details of a segment plan identified by the `segmentPlanId`. This is a partial update, meaning that only the provided fields will be updated. ***Note***: Updating `origin` and `destination` is prohibited to prevent breaking the chain of locations.

Updates a shipment details Updates details of a shipment identified by the `shipmentId`. This is a partial update, meaning that only the provided fields will be updated, except when updating segments, the whole segments will be replaced fully. Changing the status of the shipment affects the statuses of the segments. The following status changes are allowed: * `pending` → `ongoing` * changes the status of the first segment to `ongoing` * `pending` → `cancelled` * changes the status of all segments to `cancelled` * `ongoing` → `cancelled` * cancels the current `ongoing` segment and all the succeeding segments * `ongoing` → `completed` * completes the current `ongoing` segment and cancels all the succeeding segments ***Note***: `segments` and `autoStart` can be updated via this API call only if the shipment is in `pending` state.

Updates a segment details Updates details of a segment identified by the `segmentId`. This is a partial update, meaning that only the provided fields will be updated. Changing the status of a segment affects the statuses of other segments in the shipment. The following status changes are allowed: * `pending` → `ongoing` * changes previous `pending` segments to `cancelled` * changes previous `ongoing` segment to `completed` (only for the immediate predecessor of this segment) * changes previous `ongoing` segment to `cancelled` (for segments that are not immediate predecessors of this segment) * previous segments in `cancelled` or `completed` states are not affected * `pending` || `ongoing` → `cancelled` * no changes for other segments * `ongoing` → `completed` * next segment with status `pending` is changed to `ongoing` ***Note***: `trackingId` can be updated through this API call only if the segment is in `pending` state.

Associates rules with a device Associates rules with the device `trackingId`.

Disassociates rules from a device Disassociates rules from the device identified by `trackingId`.

Starts bulk upload process

Receives external device update reports External clouds can call this endpoint through their callback mechanism to report device updates. The format of the payload is driver specific.

Creates a connector Registers a cloud-to-cloud connector between the HERE Tracking project `projectId` and an external cloud using the cloud-to-cloud driver `driverId` and the external cloud access credentials.

Adds external devices to a connector Adds external devices to the connector `connectorId`.

Validate and verify external cloud credentials for driver External cloud credentials to be validated for structure and fields provided. Verify external cloud authentication status.

Creates a geofence One can specify a geofence as a circle, as a polygon or as POI (Point of Interest). One can also assign a name and a description to each geofence to help identify them. Circle --- Specify coordinates of the center point of the circle and a radius in meters. ```json { "name": "Home", "type": "circle", "definition": { "center": { "lat": 52.5308398, "lng": 13.38490035 }, "radius": 100 }, "description": "Small area around my house." } ``` Polygon --- Specify an array of points. A minimum of three points is required. *NOTE: If the array of points does not describe a closed polygon, the polygon is automatically closed between the last and first points.* ```json { "name": "Work", "type": "polygon", "definition": { "points": [{ "lat": 52.5308398, "lng": 13.38490035 }, { "lat": 52.530443, "lng": 13.38482003 }, { "lat": 52.5308298, "lng": 13.38492235 }] }, "description": "The area around work." } ``` Indoor geofence --- Circular and polygonal geofences can be both outdoors and indoors. To create a `circular` `indoor` geofence, add the `floor` property to the request body. ```json { "name": "Office indoor", "type": "circle", "definition": { "center": { "lat": 52.5308398, "lng": 13.38490035 }, "radius": 20, "floor": { "level": 2, "id": "DM_1234", "name": "Office floor 2" } }, "description": "Floor 2 of the office." } ``` POI geofence --- Specify location details of a POI geofence for its initial creation. After the POI geofence has been created, it will need to be trained. The POI geofence boundary is defined using radio measurements. The POI geofence is trained using a telemetry that a device has ingested while being at this desired point of interest. For a trained POI geofence, an associated device is considered to be inside the geofence when the radio measurements of the device-ingested telemetry and the training data match. ```json { "name": "POI room in the office", "type": "poi", "definition": { "location": { "room": ROOM_201, "address": Invalidenstrasse 116, "country": Germany, "position": { "lat": 52.5308398, "lng": 13.38490035 } }, "floor": { "level": 2, "id": "DM_1234", "name": "Office floor 2" } }, "description": "A room where goods should be delivered." } ``` Successful requests have the HTTP status 201 and the response body provides the ID of the created geofence.

Trains a POI geofence Trains the POI geofence `geofenceId` using a device telemetry. The POI geofence boundary is defined using radio measurements. The geofence is trained using a telemetry that the device with `trackingId` has ingested during the specified time range, while being at this point of interest. Only telemetries that have been ingested during the last 24 hours can be used in the training. Optionally, a WLAN scan be used for the training.

Checks if a POI geofence training is possible with the given parameters Checks if a POI geofence training is possible with the given request parameters. The request body contains a training data sample in form of either a device tracking ID along with a specific time range for the ingested device telemetry or a WLAN scan.

Creates a new data upload Creates a new multipart large data upload. Response contains `dataId`, which is the created large data object identifier.

Completes data upload After all parts have been uploaded, this operation completes the upload. When the upload has been completed, it is no longer possible to upload new parts to it but the uploaded data can be downloaded. This request has an optional `abort` query parameter (the default value is `false`) for aborting the upload instead of successfully completing it. If the upload is aborted, all of its parts and data are removed from HERE Tracking.

Creates a location Creates a new location. A location consists of latitude/longitude coordinate pair and/or geofenceId. A name, description, and address of the location may be provided.

Gets a batch of metadata of multiple devices or shipments. The device or shipment IDs are specified in the request body.

Gets a batch of metadata of multiple geofences. The geofences IDs are specified in the request body.

Gets a batch of metadata for multiple sensor rules Gets a batch of metadata of multiple sensor rules. The sensor rules IDs are specified in the request body.

Registers for notifications User can subscribe to notifications of all events triggered by device telemetry and rules and geofences. To get notified about some specific events only, one can set up `ruleId`, `eventSource`, `eventType` and `initialState` filters for a notification channel.

Creates licenses for multiple devices Starts a batch job to create licenses for either physical devices or virtual devices. Virtual devices are meant for cloud-to-cloud use case. A physical device license is a `deviceId` and `deviceSecret` credential pair. The batch job creates a number of physical device licenses specified by the `count` parameter in the request body. The response contains an array of `deviceId` and `deviceSecret` pairs. Virtual devices are identified with an external device ID and the requestor's project `appId`. The virtual device external ID is application-specific and the user is free to allocate it as user finds suitable. The external IDs for the virtual devices to be created are specified in the `devices` array in request body. For virtual devices the response contains only an array of `deviceId`s, but no `deviceSecret`s. The `autoclaim` parameter can only be used when creating virtual devices. If `autoclaim`=`true`, the created virtual devices are immediately claimed by the requesting user account. In this case the response contains also tracking IDs for the claimed devices.

Creates a license for a single physical device Device license is a `deviceId` and `deviceSecret` credential pair. The created credentials will be returned in the response body. If `autoclaim` query parameter is set to `true`, the created device will also be claimed by the same user account.

Gets all resources of a resource type Gets all resources of the resource type `resourceType`.

Starts report creation Starts a report creation. The request body contains a rule ID, and the report start and end time. The report will be created based on the event data generated by the rule and devices associated to it. The supported rule types are: * dwelling * detention * utilization > Note that both the report start and end timestamps must be earlier than the current time, > and no newly ingested data will be automatically added to the report after its creation. The created report ID will be provided in the response. The generated report is available for one week, after which it will expire and will need to be recreated. If there is an already existing report matching the request parameters, its `reportId` will be returned in the response and no new report will be generated.

Creates a rule of the specified rule `type` and with the defined `threshold`. After the rule has been created, it needs to be associated to a device to get activated. Detention rule --- For a rule of the `detention` type the threshold is defined as a duration in seconds. A `DETENTION_STARTED` event gets triggered when the device has remained stationary for longer than the threshold duration. A `DETENTION_ENDED` event will be generated when the device starts moving again. Utilization rule --- For a rule of the `utilization` type the threshold is defined as a duration in seconds. An `UNUTILIZED` event will be generated when the device has been stationary for longer than the threshold duration, and `UTILIZED` event gets triggered when the device starts moving again after having been stationary. Dwelling rule --- For a rule of the `dwelling` type the threshold is defined as a duration in seconds. A `DWELLING_STARTED` event gets triggered when a dwelling time of the device inside any device-associated geofence exceeds the threshold duration. When the device exits the geofence, a `DWELLING_ENDED` event will be generated. Online rule --- For a rule of the `online` type there is no threshold defined. A `TRUE_TO_FALSE` event gets triggered when the device is late for the planned ingestion schedule by more than 5 minutes. A `FALSE_TO_TRUE` event is generated when the device starts ingesting again after having been offline. The planned ingestion schedule needs to be configured in the device `desired shadow` (the `desired.system.rate.sendMs` property). Stock rule --- For a rule of the `stock` type the threshold is defined as `minVolume` and/or `maxVolume` values. When creating a stock rule, also a geofence ID needs to be specified. When the number of devices inside the specified geofence exceeds `maxVolume`, an `OVERSTOCK` event will be generated. Similarly, when the number of devices inside the specified geofence gets below `minVolume`, an `UNDERSTOCK` event will be generated. When the number of devices inside the specified geofence is between `minVolume` and `maxVolume`, a `NORMAL_VOLUME` event will be generated. Note that the stock rule only gets triggered for devices that are associated to the specified geofence. Shipment schedule rule --- For a rule of the `shipmentSchedule` type there are `before` and `after` deviation time thresholds from the planned shipment ETD/ETA. A `SHIPMENT_EARLY` event gets triggered when the shipment is ahead of schedule by the number of `before` seconds. A `SHIPMENT_DELAYED` event gets triggered when the shipment is behind schedule by the number of `after` seconds. A `SHIPMENT_ON_TIME` event gets triggered when the shipment is on time. When a rule has been successfully created, the response body will contain the created rule ID.

Creates a sensor rule of the specified rule type. After the sensor rule has been created, it needs to be associated to a device to get activated. For a sensor rule of the battery, humidity, pressure and temperature type, a `range` parameter needs to be specified, defining both upper and lower thresholds for the sensor readings. When the device ingests data, the reported sensor reading is compared to the defined range and in case in or out of range transition has taken place, an event gets triggered. For a sensor rule of the acceleration type, a `threshold` parameter needs to be specified, defining the acceleration threshold value. Every time the device reports its accelerometer sensor reading being above the threshold, an event gets triggered. For a sensor rule of the attach and tamper types, no additional parameters need to be specified. The attach sensor detects whether the device is attached to some object (for example to an asset). The tamper sensor detects whether the device cover is open or closed. When the cover is open, the device is considered to be tampered with. Every time the device reports getting attached, detached, tampered with or left with the cover closed (that is, not tampered with), an event gets triggered. When a sensor rule has been successfully created, the response body will contain the created rule ID.

Gets a batch of device shadows Gets device shadows for multiple devices. One can get shadows for a maximum of 100 devices per request. In case `after` parameter is provided, only the device shadows that were modified on or after the specified timestamp will be retrieved.

Starts shipment report generation This endpoint starts the shipment report generation. One can specify which shipments to include in the shipments report by using the filters in the request body. The response contains the generated shipment report ID `shipmentReportId`. After the shipment report generation has been requested, the status of the shipment report generation can be checked by using the `/shipment-reports/v4/{shipmentReportId}/status` endpoint.

Creates a shipment Creates a new shipment. A shipment consists of segments each representing a part of the logistics journey. A segment spans from a location to another and each segment may be assigned a different tracking device. The segments of the shipment must form a continuous chain of locations, that is the origin of a segment must match the destination of a previous segment.

Creates a shipment plan Creates a new shipment plan. A shipment plan is a structure that holds information about a recurring shipment. Like a shipment, a shipment plan also consists of segments each representing a part of the logistics journey. A segment spans from a location to another and each segment may be assigned a different tracking device. The segments of the shipment must form a continuous chain of locations, that is the origin of a segment must match the destination of a previous segment. In addition to shipments, a predefined duration can be assigned to each segment in the plan. This information will be used to calculate the Estimated Time of Departure (ETD) and Estimated Time of Arrival (ETA) when instantiating a shipment from a shipment plan.

Gets a user access token Authenticates a user with an email and a password and gets a user access token upon the successful authentication. The user email must be registered with a valid [HERE Account](https://account.here.com). Optionally user can provide requested realm ID.

Gets a renewed user access token Gets a new valid user access token for a given previous access token and a refresh token.

Gets a project-scoped user access token Takes user access token, requested scope and returns project-scoped user access token.

Ingests data and receives a shadow Devices can use this end point to ingest data into HERE Tracking, in the same way as via the `/v3` endpoint. A device uses its access token obtained via the the `/v2/token` endpoint to send telemetry – GPS position, sensor readings, WLAN or Bluetooth scans - to HERE Tracking. By default the request is synchronous and the response will be the device `desired` shadow. If the request is set to be asynchronous, the response will be empty. The device position gets resolved based on the `position` and `scan` objects provided in the request body (see the objects definitions for details). If only `position` is provided, it will be used as the device position. If only `scan` is provided, the position will be resolved asynchronously via the HERE Positioning API after returning a response. If both are provided, `scan` is resolved to a position via the HERE Positioning API, and the better of the two positions (provided vs. resolved) will be selected. If neither `position` nor `scan` is provided, or if the HERE Positioning API is not able to resolve the position, the device position will be left empty. The `reported` shadow will be updated with the device latest position information, sensor readings and settings ingested by the device. The reported shadow may also contain additional properties generated by HERE Tracking based on the device-ingested telemetry. Such properties are stored in the `system.computed` property of the shadow. The device shadow can be queried via the `shadows/v2/{trackingId}` endpoint. The data ingested by the device will be available as a device trace via the `traces/v2/{trackingId}` endpoint.

Requests a token for a registered device Authenticates a device to HERE Tracking and requests a device access token. A device must provide a valid device access token when it sends telemetry to HERE Tracking. Tokens can be obtained upon a successful device authentication. The device token requests must be signed. The signature method uses the OAuth 1.0 standard. For more information on this standard, see the [OAuth Core 1.0](https://oauth.net/core/1.0/) specification. Tokens can be requested only by claimed devices. A claimed device license, that is ```deviceId``` and ```deviceSecret``` credential pair, is used for creating a signed token request. > See the Authentication section for details on how to generate a signed token request. > A new signature must be created for each device access token request. > Signatures can only be used once.

Ingests data for a device and receives a shadow Devices can use this end point to ingest data into HERE Tracking. A device uses its access token obtained via the the `/v2/token` endpoint to send telemetry – GPS position, sensor readings, WLAN or Bluetooth scans - to HERE Tracking. Also device owners use this end point to ingest data on behalf of a device. The device can be either a real or a virtual device. A real device is identified by a `trackingId` assigned to it when the device was claimed. A virtual device is identified by an external device ID and the owner's project `appId`. In case the ingestion is done by a device owner, the owner should first authenticate himself with HERE Tracking and obtain a user access token via the `/users/v2/login` endpoint. The user access token will then be used in this API call. By default the request is synchronous and the response will be the device `desired` shadow. If the request is set to be asynchronous, the response will be empty. The device position gets resolved based on the `position` and `scan` objects provided in the request body (see the objects definitions for details). If only `position` is provided, it will be used as the device position. If only `scan` is provided, the position will be resolved asynchronously via the HERE Positioning API after returning a response. If both are provided, `scan` is resolved to a position via the HERE Positioning API, and the better of the two positions (provided vs. resolved) will be selected. If neither `position` nor `scan` is provided, or if the HERE Positioning API is not able to resolve the position, the device position will be left empty. The `reported` shadow will be updated with the device latest position information, sensor readings and settings ingested by the device. The reported shadow may also contain additional properties generated by HERE Tracking based on the device-ingested telemetry. Such properties are stored in the `system.computed` property of the shadow. The device shadow can be queried via the `shadows/v2/{trackingId}` endpoint. The data ingested by the device will be available as a device trace via the `traces/v2/{trackingId}` endpoint.

Ingests data for multiple devices Device owner use this endpoint to ingest data to HERE Tracking on behalf of multiple devices. A single request can contain data for multiple devices. The devices can be either real or virtual. A real device is identified by a `trackingId` assigned to it when the device was claimed. A virtual device is identified by an external device ID and the owner's project `appId`. Prior to making the request, the device owner should first authenticate himself with HERE Tracking and obtain a user access token. The user access token will then be used in this API call. For more information on the device position resolution, and the device shadow and trace updates, see the `/v3` endpoint description.

Creates multiple aliases for a device Creates a set of aliases for a device identified by the `trackingId`. An alias must be unique within a project.

Creates an alias for the `trackingId`. An alias must be unique within a project.

Updates rules associations for devices Updates rules associated with devices.

Associates a device to a geofence Associates the device with `trackingId` to the geofence with `geofenceId`. Whenever the device enters or exits the associated geofence, an event is generated.

Associates a device to a rule Associates the device with `trackingId` to the rule with `ruleId`. Whenever the device behaviour triggers the rule, an event is generated.