here.com – tracking

Tools (218)

Extracted live via the executor SDK.

• aliases.deleteAliasesV2TrackingId

  Deletes all aliases of a device identified by the trackingId.

  Note that one needs to supply an HTTP header x-confirm with the value true to force the deletion. If the header is not provided, the request will fail.

• aliases.deleteAliasesV2TrackingIdType

  Deletes all aliases of a specified type for a device identified by the trackingId.

  Note that one needs to supply an HTTP header x-confirm with the value true to force the deletion. If the header is not provided, the request will fail.

• aliases.deleteAliasesV2TrackingIdTypeExternalId

  Deletes the specified alias.

• aliases.getAliasesV2

  Gets all aliases of a project.

  If type query parameter is provided, the response will contain only aliases of the given type.

  If externalId query parameter is specified, the response will contain only aliases that match the given external ID. The following wildcards can be used: '*' matches any number of any characters, '?' matches a single character.

  If after query parameter is provided, the successful response will only contain aliases that were created after the specified timestamp. Parameters after and pageToken are mutually exclusive and cannot be provided at the same time.

  The returned results are sorted in ascending order by the alias creation time. *

• aliases.getAliasesV2Health

  Gets service health

• aliases.getAliasesV2TrackingIdType

  Gets all aliases of a specified type for a device identified by the trackingId.

• aliases.getAliasesV2Version

  Gets service version

• aliases.putAliasesV2TrackingIdBatch

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

• aliases.putAliasesV2TrackingIdTypeExternalId

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

• aliases.v2.getAliasesV2TrackingIdGet0010uutl

  Gets the trackingId associated with an alias.

• aliases.v2.getAliasesV2TrackingIdGet00na56kr

  Gets all aliases of a device identified by the trackingId.

  If the request is supplied with a type query parameter, the response will contain only aliases of the given type.

• associations.deleteAssociationsV3TrackingIdGeofencesGeofenceId

  Deletes an association between the geofence geofenceId and the device trackingId.

• associations.deleteAssociationsV3TrackingIdRulesRuleId

  Deletes an association between the rule ruleId and the device trackingId.

• associations.deleteAssociationsV3TrackingIdSensorsSensorRuleId

  Deletes the association between the sensor rule sensorRuleId and the device trackingId.

• associations.getAssociationsV3GeofencesGeofenceId

  Gets all devices associated with the geofence geofenceId.

• associations.getAssociationsV3Health

  Gets service health

• associations.getAssociationsV3RulesRuleId

  Gets all devices associated with the rule ruleId.

• associations.getAssociationsV3SensorsSensorRuleId

  Gets all devices associated with the sensor rule sensorRuleId.

• associations.getAssociationsV3TrackingIdGeofences

  Gets a list of geofences associated with the device trackingId.

• associations.getAssociationsV3TrackingIdRules

  Gets a list of rules associated with the device trackingId.

• associations.getAssociationsV3TrackingIdSensors

  Gets a list of sensor rules associated with the device trackingId.

• associations.getAssociationsV3Version

  Gets service version

• associations.postAssociationsV3DevicesTrackingIdBatchCreate

  Associates rules with the device trackingId.

• associations.postAssociationsV3DevicesTrackingIdBatchDelete

  Disassociates rules from the device identified by trackingId.

• associations.putAssociationsV3DevicesBatchUpdate

  Updates rules associated with devices.

• associations.putAssociationsV3TrackingIdGeofencesGeofenceId

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

• associations.putAssociationsV3TrackingIdRulesRuleId

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

• associations.putAssociationsV3TrackingIdSensorsSensorRuleId

  Associates the device with trackingId to the sensor rule with sensorRuleId.

  A single device can only have one sensor rule per sensor type associated.

  The associated sensor rule settings will be automatically synchronised to the system.sensorAlarmConfig section of the device desired shadow.

  Every time the associated sensor rule gets triggered by the device ingestion, an event will be generated.

• bulkJobs.getBulkjobsV4DeviceUploads

  Gets the bulk upload job IDs for a project. The jobs and their results are available for one week.

• bulkJobs.getBulkjobsV4DeviceUploadsJobIdResults

  Gets bulk upload results

• bulkJobs.getBulkjobsV4DeviceUploadsJobIdStatus

  Gets bulk upload status and progress

• bulkJobs.getBulkjobsV4Health

  Gets service health

• bulkJobs.getBulkjobsV4Version

  Gets service version

• bulkJobs.patchBulkjobsV4DeviceUploadsJobId

  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.

• bulkJobs.postBulkjobsV4DeviceUploads

  Starts bulk upload process

• c2C.deleteC2cV4ConnectorsConnectorId

  Deletes the connector connectorId.

• c2C.deleteC2cV4ConnectorsConnectorIdExtDevicesBatch

  Removes a batch of external devices from the connector connectorId.

• c2C.deleteC2cV4ConnectorsConnectorIdExtDevicesExternalDeviceId

  Removes the external device externalDeviceId from the connector connectorId.

• c2C.getC2cV4Connectors

  Gets a list of cloud-to-cloud connectors for the project projectId.

• c2C.getC2cV4ConnectorsConnectorId

  Gets connector info for the connector connectorId.

• c2C.getC2cV4ConnectorsConnectorIdExtDevices

  Gets all external devices under the connector connectorId.

• c2C.getC2cV4ConnectorsExtDevicesExternalDeviceId

  Gets identifiers for connectors to which an external device belongs.

• c2C.getC2cV4Drivers

  Gets all cloud-to-cloud drivers that a user is authorized to use.

• c2C.getC2cV4Health

  Gets service health

• c2C.getC2cV4Version

  Gets service version

• c2C.postC2cV4Callback

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

• c2C.postC2cV4Connectors

  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.

• c2C.postC2cV4ConnectorsConnectorIdExtDevices

  Adds external devices to the connector connectorId.

• c2C.postC2cV4DriversDriverIdVerify

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

• c2C.putC2cV4ConnectorsConnectorId

  Updates the connector connectorId info.

• deviceAssociations.getDeviceAssociationsV2Health

  Gets service health

• deviceAssociations.getDeviceAssociationsV2TrackingIdGeofences

  Gets all geofences associated with the device with trackingId.

• deviceAssociations.getDeviceAssociationsV2Version

  Gets service version

• events.getEventsV3

  Gets all events for all devices and shipments of the project. The results are listed in descending order based on the timestamp.

  An event is uniquely identified by trackingId-ruleId-timestamp key, with an exception of dwelling and stock rule events. Dwelling events also need geofenceId to be specified, whereas for stock events trackingId is not applicable.

  A time range can be defined with before and after timestamps. The response will contain an array of events that were recorded within the range.

  If the request is supplied with eventSource query parameter, the response will contain events generated by the defined source only.

  If the request is supplied with eventType query parameter, the response will contain events of the specified type only.

  If the request is supplied with ruleId query parameter, the response will only contain events for the specified rule ID.

  If the request is supplied with initialState query parameter, the response will contain events having the specified initial state.

  All the aforementioned query parameters can be combined together.

• events.getEventsV3Health

  Gets service health

• events.getEventsV3Statuses

  Gets all events statuses for all devices and shipments of the project. An event status of a device is the most recent event of any rule or geofence the device is associated with. The same applies for shipments.

  The response contains a list of event status objects and each object has the following properties:

  • trackingId or shipmentId: a device ID or a shipment ID
  • ruleId: an associated rule or geofence ID
  • eventSource: the rule type
  • eventType: an event type of the latest event of the rule (same as the "event state")
  • timestamp: a time since when the device has been in this event state

  The array is sorted by the following fields in the following order: trackingId, eventSource, timestamp, ruleId, geofenceId.

  A time range can be defined with before and after timestamps. The response will contain event statuses that were recorded within the range.

  If the request is supplied with eventSource query parameter, the response results will be limited to the specified rule types only.

  If the request is supplied with ruleId query parameter, the response results will be limited to the specified rule IDs only.

  If the request is supplied with trackingId query parameter, the response results will be limited to the specified devices only. Also shipmentId can be used as a trackingId.

  If the request is supplied with eventType query parameter, the response results will be limited to the specified type only.

  If the request is supplied with geofenceId query parameter, it will only affect dwelling event statuses filtering, limiting the results to the specified geofence only. Other event types are not affected by this setting. Note that for the event statuses of geofence type, the ruleId is the geofenceId.

  If the request is supplied with shipments query parameter, the response results will be limited either to shipments (shipments=true) or devices (shipments=false) only. Otherwise, if shipments query parameter is not specified, response results will include both devices and shipments.

  All the aforementioned query parameters can be combined together.

• events.getEventsV3StatusesDeviceCounts

  This API call counts the number of devices and shipments that are currently in the different event states per rule or per event source (that is per rule type).

  An event state of a device is the event type of the most recent device event. It indicates a state the device is currently in, in relation to a rule the device is associated with.

  For example, the event state can be either INSIDE_GEOFENCE or OUTSIDE_GEOFENCE in case the event source is geofence; or BELOW_RANGE, IN_RANGE or ABOVE_RANGE in case the event source is battery rule.

  A device can be in several different event states at the same time when it has more than one rule associated with it. For example, a device can be at the same time in INSIDE_GEOFENCE and ABOVE_RANGE event states.

  The same applies for shipments.

  The groupBy query parameter defines how the results are grouped.

  The default value for the groupBy parameter is ruleId. The response contains a list of objects, one per each rule, that are associated to at least one device or shipment of the project. Each object has the following properties:

  • ruleId: a rule ID
  • eventSource: the rule type
  • every distinct event state (applicable for the rule type) and the number of devices in this state
  • total: the total number of devices associated to the rule

  When the groupBy parameter value is eventSource, the response contains a list of objects, one per event source (that is per each rule type), that are associated to at least one device or shipment of the project. Each object has the following properties:

  • eventSource: a rule type
  • every distinct event state (applicable for the rule type) and the number of devices in this state. One device is counted only once per eventType state, but in case a single device is associated to multiple rules of the same type, it will be counted separately for each event state.
  • total: the total number of devices associated to the rule type. A single device is counted only once.

  For example, a device A is associated to 2 geofences and is inside one and outside the other. A device B is associated to 3 geofences and is outside all of them. With the request query parameter set as groupBy=eventSource, the response body will contain the following result item:

  {  "eventSource": "geofence",  "INSIDE_GEOFENCE": 1,  "OUTSIDE_GEOFENCE": 2,  "total": 2}.

  If the request is supplied with eventSource query parameter, the response results will be limited to the specified rule types only.

  If the request is supplied with ruleId query parameter, the response results will be limited to the specified rule IDs only.

  If the request is supplied with trackingId query parameter, the response results will be limited to the specified devices only. Also shipmentId can be used as a trackingId.

  If the request is supplied with geofenceId query parameter, it will only affect dwelling event statuses filtering, limiting the results to the specified geofence only. Other event types are not affected by this setting. Note that for the event statuses of geofence type, the ruleId is the geofenceId.

  If the request is supplied with shipments query parameter, the response results will be limited either to shipments (shipments=true) or devices (shipments=false) only. Otherwise, if shipments query parameter is not specified, response results will include both devices and shipments.

  All the aforementioned query parameters can be combined together.

• events.getEventsV3TrackingId

  Gets all events for a device or a shipment. A device is identified by the trackingId. For shipments, shipmentId can be used as a trackingId.

  The results are listed in descending order based on the timestamp.

  An event is uniquely identified by trackingId-ruleId-timestamp key, with an exception of dwelling and stock rule events. Dwelling events also need geofenceId to be specified, whereas for stock events trackingId is not applicable.

  A single event can be fetched using ruleId, before and after query parameters.

  A time range can be defined with before and after timestamps. The response will contain an array of events that were recorded within the range.

  If the request is supplied with eventSource query parameter, the response will contain events generated by the defined source only.

  If the request is supplied with eventType query parameter, the response will contain events of the specified type only.

  If the request is supplied with ruleId query parameter, the response will only contain events for the specified rule ID.

  If the request is supplied with initialState query parameter, the response will contain events having the specified initial state.

  All the aforementioned query parameters can be combined together.

• events.getEventsV3Version

  Gets service version

• geofenceAssociations.deleteGeofenceAssociationsV2GeofenceIdTrackingId

  Deletes an association between the geofence geofenceId and the device trackingId.

• geofenceAssociations.getGeofenceAssociationsV2GeofenceIdDevices

  Returns all devices associated with the geofence geofenceId.

• geofenceAssociations.getGeofenceAssociationsV2Health

  Gets service health

• geofenceAssociations.getGeofenceAssociationsV2Version

  Gets service version

• geofenceAssociations.putGeofenceAssociationsV2GeofenceIdTrackingId

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

• geofences.deleteGeofencesV2

  Deletes all geofences of a project.

  If a geofence is associated with a stock rule, the rule will also be deleted.

  Note that one needs to supply an HTTP header x-confirm with the value true to force the deletion. If the header is not provided, the request will fail.

• geofences.deleteGeofencesV2GeofenceId

  Deletes a single geofence identified by the geofenceId.

• geofences.getGeofencesV2

  Gets all geofences of a project. Results can be filtered by using the query parameters. Indoor geofences with the floor properties may be filtered by floor[id], which specifies the ID of the venue associated with the geofence.

• geofences.getGeofencesV2GeofenceId

  Gets details of a single geofence identified by the geofenceId.

• geofences.getGeofencesV2Health

  Gets service health

• geofences.getGeofencesV2Version

  Gets service version

• geofences.postGeofencesV2

  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.

• geofences.postGeofencesV2GeofenceIdPoiTraining

  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.

• geofences.postGeofencesV2TrainingTest

  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.

• geofences.putGeofencesV2GeofenceId

  Updates the geofence type, name, description or definition property. The old geofence will be replaced by the new one, and hence the full set of the geofence properties must be provided in the request body. POI geofence type cannot be changed to circle or polygon and vice versa.

  If the update was successful, the response will contain the updated geofence details.

• ingestion.getV2Health

  Gets service health

• ingestion.getV2Timestamp

  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.

• ingestion.getV2Version

  Gets service version

• ingestion.getV3Health

  Gets service health

• ingestion.getV3Version

  Gets service version

• ingestion.postV2

  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.

• ingestion.postV2Token

  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 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.

• ingestion.postV3

  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.

• ingestion.postV3Batch

  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.

• labels.deleteLabelsV4ResourceTypeResourceId

  Deletes all labels of the resource resourceId.

• labels.deleteLabelsV4ResourceTypeResourceIdKey

  Deletes all the labels that have the key key of the resource resourceId.

• labels.deleteLabelsV4ResourceTypeResourceIdKeyValue

  Deletes the label key-value of the resource resourceId.

• labels.getLabelsV4Health

  Gets service health

• labels.getLabelsV4ResourceType

  Gets all labels of the resource type resourceType within a project.

  The fields parameter specifies which fields should be added to the response body (for example, resourceId).

  The labels query parameter is specified as a label filter, and only the matching results will be returned:

  "?labels[priority]=high&labels[group]=group1&fields=resourceId,labels" "?labels[group]=*" *

• labels.getLabelsV4ResourceTypeKeys

  Gets all label keys of the resource type resourceType.

• labels.getLabelsV4ResourceTypeKeysKeyValues

  Gets all values of the label key for the resource type resourceType.

• labels.getLabelsV4ResourceTypeResourceId

  Gets all labels of the resource resourceId.

• labels.getLabelsV4Version

  Gets service version

• labels.putLabelsV4ResourceTypeResourceIdBatch

  Creates a set of labels for the resource resourceId.

• labels.putLabelsV4ResourceTypeResourceIdKeyValue

  Creates a label for the resource resourceId.

• largedata.deleteLargedataV4DataId

  Deletes large data object.

• largedata.getLargedataV4DataIdData

  Downloads a part of large data.

  The data to be downloaded is identified with dataId. offset query paremeter specifies the first byte of the data, and count indicates how many bytes of the data is to be downloaded starting from and including the offset. The default value for offset is zero and the for count it is the total size of the data.

  The size of one downloaded data part must be between 1 byte and 10 MB.

• largedata.getLargedataV4DataIdMetadata

  Gets metadata for a large data object.

• largedata.getLargedataV4DataIdParts

  Gets information about uploaded parts for a large data object.

• largedata.getLargedataV4DevicesTrackingIdMetadata

  Gets metadata listing for all large data objects for a given device.

• largedata.getLargedataV4Health

  Gets service health

• largedata.getLargedataV4Version

  Gets service version

• largedata.postLargedataV4

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

• largedata.postLargedataV4DataId

  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.

• largedata.putLargedataV4DataIdPartsPartNumber

  Uploads a part of large data. The part is identified with dataId and a part number.

  Part upload has the following limits:

  • The part numbers must start from 1, be no greater than 10000 and be consecutive.
  • The size of one uploaded data part must be between 1 byte and 1 MB.
  • Parts re-uploaded with the same partNumber are overridden.
  • Only application/octet-stream Content-Type is supported.

  Parts can be uploaded in any order, the partNumber determines their position in the total data.

  The optional md5 query parameter can be used to provide the MD5 digest for the uploaded data part. If it is specified and does not match to the received data, HERE Tracking returns HTTP status 400.

  If the data upload is still in preparing state, HERE Tracking returns HTTP status 409.

• locations.deleteLocationsV4

  Deletes all locations of the project.

  Note that one needs to supply an HTTP header x-confirm with the value true to force the deletion. If the header is not provided, the request will fail.

• locations.deleteLocationsV4LocationId

  Deletes the location locationId.

  NOTE: A location can not be deleted if the location is referred by any shipment or shipment plan.

• locations.getLocationsV4

  Gets all locations of the project.

• locations.getLocationsV4Health

  Gets service health

• locations.getLocationsV4LocationId

  Gets details of the location locationId.

• locations.getLocationsV4Version

  Gets service version

• locations.postLocationsV4

  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.

• locations.putLocationsV4LocationId

  Updates the location locationId details. A location consists of latitude/longitude coordinate pair and/or geofenceId. A name, description, and address of the location may be provided. The old location definition will be replaced, meaning that full location body should be provided. After a successful update, the response provides the updated location details.

• metadata.deleteMetadataV2DevicesTrackingId

  Deletes all the metadata of the device or a shipment identified by the trackingId or the shipmentId.

• metadata.deleteMetadataV2GeofencesGeofenceId

  Deletes all the metadata of the geofence identified by the geofenceId.

• metadata.deleteMetadataV2SensorRulesSensorRuleId

  Delete all the metadata of the sensor rule identified by the sensorRuleId.

• metadata.getMetadataV2DevicesTrackingId

  Gets metadata of a device or a shipment identified by the trackingId or the shipmentId.

• metadata.getMetadataV2GeofencesGeofenceId

  Gets metadata of the geofence identified by the geofenceId.

• metadata.getMetadataV2Health

  Gets service health

• metadata.getMetadataV2SensorRulesSensorRuleId

  Gets metadata of the sensor rule identified by the sensorRuleId.

• metadata.getMetadataV2Version

  Gets service version

• metadata.postMetadataV2DevicesBatch

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

• metadata.postMetadataV2GeofencesBatch

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

• metadata.postMetadataV2SensorRulesBatch

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

• metadata.putMetadataV2DevicesTrackingId

  Updates the metadata object of the device or a shipment identified by the trackingId or the shipmentId. The metadata specified in the request body is merged with the existing metadata object (or gets created if no metadata object exists); new keys are added, and the values of the existing keys are updated with the new data. Adding 'null' value for a key deletes it from the metadata object. Successful response body contains the updated metadata object.

• metadata.putMetadataV2GeofencesGeofenceId

  Updates the metadata object of the geofence identified by the geofenceId. The metadata specified in the request body is merged with the existing metadata object (or gets created if no metadata object exists); new keys are added, and the values of the existing keys are updated with the new data. Adding 'null' value for a key deletes it from the metadata object. Successful response body contains the updated metadata object.

• metadata.putMetadataV2SensorRulesSensorRuleId

  Updates the metadata object of the sensor rule identified by the sensorRuleId. The metadata specified in the request body is merged with the existing metadata object (or gets created if no metadata object exists); new keys are added, and the values of the existing keys are updated with the new data. Adding 'null' value for a key deletes it from the metadata object. Successful response body contains the updated metadata object.

• notifications.deleteNotificationsV3RegistrationChannelId

  Unregisters from notifications and deletes the notification channel channelId.

• notifications.deleteNotificationsV3Registrations

  Deletes all the notification channels. This would result in unregistering from all the notifications.

  Note that one needs to supply an HTTP header x-confirm with the value true to force the deletion. If the header is not provided, the request will fail.

• notifications.getNotificationsV3Health

  Gets service health

• notifications.getNotificationsV3RegistrationChannelId

  Gets details of the notification channel channelId.

• notifications.getNotificationsV3Registrations

  Gets a list of all registered notification channels.

• notifications.getNotificationsV3Version

  Gets service version

• notifications.postNotificationsV3Registrations

  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.

• notifications.putNotificationsV3RegistrationChannelId

  Updates the url, ruleId, eventSource, eventType and initialState parameters of the notification channel channelId. If a property is not provided in the request body, its value will be updated to null. When updating a webhook channel, the url parameter must be provided.

  After a successful update, the response provides the updated notification channel details.

• registry.deleteRegistryV2DevicesDeviceOrExternalId

  Deactivates a provisioned device. This operation will deactivate the device license (deviceId and deviceSecret). Deactivated devices cannot be claimed anymore.

  NOTE: The device must be unclaimed before it can be deactivated.

• registry.deleteRegistryV2TrackingId

  Unclaims a device removing the ownership association between the user and the device. The device data will no longer be accessible to the user. The device can then be reclaimed by a different or the same user.

• registry.getRegistryV2AppIdDevices

  Lists all the devices provisioned by a user project identified by the appId.

• registry.getRegistryV2AppIdLicenseCount

  Gets a number of provisioned device licenses for a user project identified by the appId.

• registry.getRegistryV2DevicesDeviceOrExternalId

  Gets the trackingId for a claimed device by its deviceId.

• registry.getRegistryV2Health

  Gets service health

• registry.getRegistryV2JobIdResults

  Gets results of a previously created multiple device license request batch job upon its successful completion.

• registry.getRegistryV2JobIdStatus

  Checks the progress of a previously created multiple device license request batch job.

• registry.getRegistryV2Licenses

  Gets a list of projects the user is a member of, along with the license information details for each project.

• registry.getRegistryV2TrackingId

  Gets the deviceId of a claimed device by its trackingId.

• registry.getRegistryV2Version

  Gets service version

• registry.postRegistryV2AppIdDevices

  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 deviceIds, but no deviceSecrets.

  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.

• registry.postRegistryV2AppIdOneDevice

  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.

• registry.postRegistryV4ResourcesResourceTypeFind

  Gets all resources of the resource type resourceType.

• registry.putRegistryV2DevicesDeviceOrExternalId

  Claims a device, associating a device to a user account. The user who claimed a device is the device owner, which is different from the device vendor.

  Unclaimed devices cannot login or send any data to HERE Tracking. A claimed device data is stored in HERE Tracking and is available to the device owner's project, which the device has been claimed to.

  When a device is claimed, it gets assigned a trackingId. This is a unique ID associated with the device data in HERE Tracking.

  trackingId is different from the deviceId. The deviceId is permanently associated with the hardware, while the trackingId is associated with the device data. If the device is later sold or transferred, the deviceId remains the same but the trackingId changes in case the device is reclaimed. This way the new owner cannot access the old data.

  If the user is a member of multiple projects, the target project ID needs to be specified in the projectId query parameter (note that this is different from the appId).

  Only users with a valid HERE Tracking license are authorized to claim new devices. Claimed devices are associated with the owner application ID, and the total device count is kept up-to-date for billing purposes.

• reports.getReportsV4Health

  Gets service health

• reports.getReportsV4ReportId

  Gets the report creation status and makes queries to fetch the actual reports. Each report request can have a different set of query parameters.

  Note that in the report context an asset is a device.

  Examples

  To get a report on assets dwelling times in the specified geofence during the report period, create a request specifying the following:

  • reportId: ID of a report created for a dwelling rule
  • measure: 'duration'
  • groupBy: 'asset'
  • geofenceId: geofence ID

  To get a report on how many times assets were in detention on average during each week of the report period, create a request specifying the following:

  • reportId: ID of a report created for a detention rule
  • measure: 'occurrence'
  • method: 'average'
  • groupBy: 'asset'
  • interval: 'week'
• reports.getReportsV4Version

  Gets service version

• reports.postReportsV4

  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.

• rules.deleteRulesV4

  Deletes all rules of the project.

  Note that one needs to supply an HTTP header x-confirm with the value true to force the deletion. If the header is not provided, the request will fail.

• rules.deleteRulesV4RuleId

  Deletes a rule identified by the ruleId.

• rules.getRulesV4

  Gets all rules definitions.

• rules.getRulesV4Health

  Gets service health

• rules.getRulesV4RuleId

  Gets details of a single rule identified by the ruleId.

• rules.getRulesV4Version

  Gets service version

• rules.postRulesV4

  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.

• rules.putRulesV4RuleId

  Updates the name, description and threshold of the rule ruleId. The rule type cannot be updated. If some of the these properties are not provided in the request body, their values will be set to null.

  If the rule has been updated successfully, the response will contain the updated rule details.

• sensors.deleteSensorsV3

  Deletes all sensor rules of a project.

  Note that one needs to supply an HTTP header x-confirm with the value true to force the deletion. If the header is not provided, the request will fail.

• sensors.deleteSensorsV3SensorRuleId

  Deletes a sensor rule identified by the sensorRuleId.

• sensors.getSensorsV3

  Gets all sensor rules definitions.

• sensors.getSensorsV3Health

  Gets service health

• sensors.getSensorsV3SensorRuleId

  Gets details of a single sensor rule identified by the sensorRuleId.

• sensors.getSensorsV3Version

  Gets service version

• sensors.postSensorsV3

  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.

• sensors.putSensorsV3SensorRuleId

  Updates the sensor rule sensorRuleId name, description and range or threshold. The sensor rule type cannot be updated. If some of the these properties are not provided in the request body, their values will be set to null. If the sensor rule has been updated successfully, the response will contain the updated rule details.

• shadows.deleteShadowsV2TrackingId

  Deletes the device shadow of the trackingId device.

  By default, all the values of the desired and reported shadow objects will be cleared, leaving them empty.

  If either desired or reported query parameter is set to false, that part of the shadow remains as it is.

• shadows.getShadowsV2Health

  Gets service health

• shadows.getShadowsV2TrackingId

  Gets the trackingId device shadow that contains both reported and desired shadows.

  If a shipmentId is used instead of a trackingId, it will return a shadow of the device that was most recently active for the shipment. If the shipment is still pending or it has been cancelled or completed, an empty shadow will be returned.

• shadows.getShadowsV2TrackingIdState

  Gets the reported or desired state object of the device trackingId, that is the reported or desired device shadow.

• shadows.getShadowsV2TrackingIdStateSelector

  Gets a value of a single property of either desired or reported state objects of a device. One can use JSON selectors to specify the target property or reference it by name. In case the property contains an object, the entire object will be returned in the response.

  The JSON selector can be nested like this: payload/time/minutes

• shadows.getShadowsV2Version

  Gets service version

• shadows.getShadowsV4

  Gets all device shadows of a project.

• shadows.postShadowsV2Batch

  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.

• shadows.putShadowsV2TrackingId

  Updates the trackingId device desired shadow.

  The device shadow consists of reported and desired shadows. Only the desired shadow can be updated via this endpoint. The reported shadow is updated automatically when the device sends telemetry to the ingestion endpoint.

• shipmentReports.getShipmentReportsV4Health

  Gets service health

• shipmentReports.getShipmentReportsV4ShipmentReportIdMetric

  Get the shipment report metric by using the shipmentReportId and a metric parameters.

  Shipment report metrics can be requested only after the shipment report generation has been completed.

• shipmentReports.getShipmentReportsV4ShipmentReportIdStatus

  Use the shipmentReportId as a path parameter for fetching the status of the generation of the shipment report.

• shipmentReports.getShipmentReportsV4ShipmentReportIdSummary

  After the shipment report generation is completed, use the shipmentReportId as a path parameter for fetching the summary of the shipment report.

  The summary contains general information about the locations, shipments, shipment plans, segments, and segment plans which were used in the generation of the shipment report. It also includes the time when the shipment report generation started, and when it ended.

• shipmentReports.getShipmentReportsV4Version

  Gets service version

• shipmentReports.postShipmentReportsV4

  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.

• shipments.deleteShipmentsV4

  Deletes all the shipments of the project.

  Note that one needs to supply an HTTP header x-confirm with the value true to force the deletion. If the header is not provided, the request will fail.

• shipments.deleteShipmentsV4Plans

  Deletes all shipment plans of the project. Any shipments instantiated from the plans will persist, but the references to the parent plans will be removed.

  Note that one needs to supply an HTTP header x-confirm with the value true to force the deletion. If the header is not provided, the request will fail.

• shipments.deleteShipmentsV4PlansShipmentPlanId

  Deletes a shipment plan identified by the shipmentPlanId.

  Any shipment instantiated from the plan will persist, but the reference to the parent plan will be removed.

• shipments.deleteShipmentsV4ShipmentId

  Deletes a shipment identified by the shipmentId. All the data related to the shipment (such as events, associations) will be removed.

• shipments.getShipmentsV4

  Gets all shipments of the project.

• shipments.getShipmentsV4Health

  Gets service health

• shipments.getShipmentsV4Plans

  Gets all shipment plans of the project.

• shipments.getShipmentsV4PlansShipmentPlanId

  Gets details of a shipment plan identified by the shipmentPlanId.

• shipments.getShipmentsV4PlansShipmentPlanIdSegmentPlanId

  Gets details of a segment plan identified by the segmentPlanId.

• shipments.getShipmentsV4ShipmentId

  Gets details of a specific shipment identified by the shipmentId.

• shipments.getShipmentsV4ShipmentIdSegmentId

  Gets details of a segment identified by the segmentId.

• shipments.getShipmentsV4TrackingIdSegments

  Gets all segments that are assigned to the device with trackingId or shipmentId.

• shipments.getShipmentsV4Version

  Gets service version

• shipments.patchShipmentsV4PlansShipmentPlanId

  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.

• shipments.patchShipmentsV4PlansShipmentPlanIdSegmentPlanId

  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.

• shipments.patchShipmentsV4ShipmentId

  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.

• shipments.patchShipmentsV4ShipmentIdSegmentId

  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.

• shipments.postShipmentsV4

  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.

• shipments.postShipmentsV4Plans

  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.

• traces.deleteTracesV2TrackingId

  Deletes all the device trackingId traces.

  This will also trigger deletion of the entire event history of the device.

• traces.getTracesV2Health

  Gets service health

• traces.getTracesV2TrackingId

  Gets all traces of the device trackingId that were recorded within the specified time range. The range is defined with before and after parameters. The returned traces are sorted in descending order based on their timestamps.

  NOTE: By default, the after parameter value is 0, and the before parameter is set to the current system time. Always make sure to specify before and after parameters explicitly, as otherwise it may take a very long time for the API call to complete.

  If the trackingId is substituted with a valid shipmentId, the response contains a composition of traces of each shipment segment. Traces are only fetched for those segments that are either in ongoing or completed state.

  The outliers parameter can be used to select only traces that have been marked as outliers (if the parameter value is true), or only traces that have not been marked as outliers (if the parameter value is false). If the outliers parameter is not present, all the traces will be returned.

  The count and pageToken parameters are used for pagination.

• traces.getTracesV2Version

  Gets service version

• transitions.getTransitionsV2DevicesTrackingId

  Gets all transitions that were recorded within a specific time range. Define the range with before and after parameters. The returned transitions are listed in descending order based on their timestamps.

  Note:

  By default, the after parameter value is 0, and the before parameter is set to the current system time. Always make sure to specify before and after parameters explicitly, as otherwise it may take a very long time for an API call to complete.

  The count and pageToken parameters are used for pagination.

• transitions.getTransitionsV2Health

  Gets service health

• transitions.getTransitionsV2Version

  Gets service version

• users.getUsersV2Devices

  Gets all devices claimed by a project.

• users.getUsersV2Health

  Gets service health

• users.getUsersV2Version

  Gets service version

• users.postUsersV2Login

  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. Optionally user can provide requested realm ID.

• users.postUsersV2Refresh

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

• users.postUsersV2TokenExchange

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

• openapi.previewSpec

  Preview an OpenAPI document before adding it as a source

• openapi.addSource

  Add an OpenAPI source and register its operations as tools