openapi: 3.2.0 info: version: 2.6.11 title: HERE Tracking Shadows API description: 'HERE Tracking is a cloud product designed to address location tracking problems for a wide range of Location IoT industry verticals. HERE Tracking also includes end-user mobile and web applications that can be used to demonstrate the product.' license: name: HERE Documentation License url: https://legal.here.com/en-gb/terms/documentation-license servers: - url: https://tracking.hereapi.com/ - url: https://tracking.api.here.com/ tags: - description: 'The Shadows service provides an effective way to manage configurations for devices that are only intermittently online.' name: Shadows paths: /shadows/v2/health: get: summary: Gets service health security: [] responses: '200': description: 'OK The service is performing as expected ' content: application/json: schema: type: object properties: message: type: string description: Health status example: message: healthy '500': description: 'Service unavailable The service is not performing as expected ' tags: - Shadows operationId: getShadowsV2Health x-operation-id-source: derived /shadows/v2/version: get: summary: Gets service version security: [] responses: '200': description: 'Success ' content: application/json: schema: description: "OK\nService returns its current version number\nschema:\n type: object\n properties:\n \"service-name\":\n type: string\n description: Version of service\n example:\n servicename: \"1.0.0\"\n" '500': description: 'Service unavailable The service is not performing as expected ' tags: - Shadows operationId: getShadowsV2Version x-operation-id-source: derived /shadows/v2/{trackingId}: parameters: - in: header name: X-Request-Id schema: type: string format: uuid description: 'ID used for correlating requests within HERE Tracking. Used for logging and error reporting. Must be a valid UUIDv4. ' required: false - name: appId description: Application identifier. Used together with an external ID to identify a virtual device. schema: type: string minLength: 8 in: query required: false put: summary: Updates a device shadow description: '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.' security: - UserToken: [] - ClientToken: [] - DeviceToken: [] parameters: - name: content-length in: header required: true description: 'The size of the shadow in bytes. The size is validated against the maximum limit of 1000 bytes. ' schema: type: number minimum: 0 maximum: 1000 - name: trackingId in: path schema: type: string minLength: 1 maxLength: 50 description: This is a unique ID associated with the device data in HERE Tracking. The `trackingId` gets assigned to a device when the device is claimed by a user. required: true requestBody: content: application/json: schema: type: object properties: desired: description: 'The desired shadow of the device. ' type: object properties: payload: type: object description: 'A free format JSON object. The maximum size is 1000B. ' system: description: 'Contains values for the device configuration. HERE Tracking uses these values for various application flows. ' type: object properties: powerSave: description: Power save mode parameters. type: object properties: sendMs: description: The rate at which to send sample results in milliseconds in power save mode. A missing or zero value means power save mode is disabled. If present must be bigger than the value of `system.rate.sendMs`. type: number minimum: 0 rate: description: This can be used to specify the rates at which the device performs certain tasks. type: object properties: sampleMs: description: The rate at which to sample signals in milliseconds. Must be smaller than the value of `system.rate.sendMs`. type: number minimum: 0 sendMs: description: The rate at which to send sample results in milliseconds type: number minimum: 0 distanceM: description: Send an update if the device has moved farther than the specified distance in meters type: number minimum: 0 syncGeofences: description: A boolean value that sets efficient geofencing on or off type: boolean detectOutliers: description: A boolean value that sets outlier detection on or off type: boolean disableTracking: type: object description: 'Tracking can be disabled and enabled by defining disableTracking object. In order to disable tracking, one must at least provide the begin time of the disabling period and define either position or sensor properties one wants to disable. One can also disable both position and sensors at the same time. By default tracking is enabled. ' properties: periods: description: 'Define begin and end of the disabling period. All trace points with timestamp that falls between begin and end times will be disabled according to the settings defined in the position and sensors properties. ' type: array minItems: 0 maxItems: 1 title: Array of periods items: type: object properties: begin: type: integer description: 'Milliseconds elapsed since 1 January 1970 00:00:00 UTC Begin time of the tracking disabling period. Begin must be smaller than end. Begin must be greater or equal to current time. Begin can be set without end. If there exists already end time which is earlier than given new begin time, the existing end time will be deleted. ' minimum: 2 maximum: 4102448400000 end: type: integer description: 'Milliseconds elapsed since 1 January 1970 00:00:00 UTC End time of the tracking disabling period. End must be greater than begin. End must be greater or equal to current time. End can be set without begin if begin is already set. ' minimum: 2 maximum: 4102448400000 position: description: Define position methods to be disabled oneOf: - type: string title: all positioning enum: - all description: 'All positioning data the device sends will be removed before further processing. No geofence and location events will be generated ' - type: array minItems: 1 title: specified positioning methods items: type: string enum: - bt - country - gsm - wcdma - tdscdma - lte - cdma - wlan - gps description: 'The items specified in the position array will be removed from the ingestion scan object before further processing. Position may be resolved by the remaining scan properties. Some geofence and location events may be generated. ' - type: string title: re-enable enum: - '' description: 'By setting the position property empty string, all positioning data will be re-enabled during the disabling period. ' sensors: description: Define sensors to be disabled oneOf: - type: string enum: - all title: all sensors description: 'All sensor data the device sends will be removed before further processing. No sensor events will be generated. ' - type: array minItems: 1 title: specified sensors items: type: string enum: - accelerationG - deviceIsAttached - deviceIsStationary - batteryIsCharging - batteryLevel - pressureHpa - relativeHumidity - deviceIsTampered - temperatureC - tiltDegree description: 'The items specified in the sensors array will be removed from the ingestion system.reportedSensorData object before further processing. Sensor events will not be generated for the disabled sensors. ' - type: string title: re-enable enum: - '' description: 'By setting the sensors property empty string, all sensors data will be re-enabled during the disabling period. ' wlanConnectivityEnabled: description: A boolean value that sets wlan connectivity on or off type: boolean wlanConfigurations: description: An array of objects that holds wlan configurations type: array minItems: 0 maxItems: 10 items: type: object properties: securityMode: description: Selected security mode type: string enum: - none - wpa2psk ssid: description: Name given to a WLAN that is used by the client to access a WLAN network. Please note that the SSID is stored to the device unencrypted. Do not use secure private networks, such as Intranet, for tracker WLAN connectivity. type: string minLength: 1 maxLength: 32 password: description: WLAN password. Please note that the password is stored to the device unencrypted. Do not use secure private networks, such as Intranet, for tracker WLAN connectivity. Password is required if security mode is other then 'none'. type: string minLength: 8 maxLength: 63 ssidIsHidden: description: Flag that informs if SSID is hidden type: boolean additionalProperties: false required: - securityMode - ssid sensorLoggingEnabled: description: Flag that sets sensor logging on or off type: boolean sensorLoggingConfigurations: description: An array of objects that holds sensor logging configurations type: array minItems: 0 maxItems: 5 items: type: object properties: type: description: Type of single sensor logging configuration type: string enum: - acceleration - pressure - temperature - humidity - gnss samplingFrequency: description: Sampling frequrency of single sensor loggin configuration (in milliseconds) type: number minimum: 1 additionalProperties: false required: - type sensorLoggingTag: description: Tag for the logged sensor data. type: string minLength: 1 maxLength: 50 additionalProperties: false additionalProperties: false required: - desired additionalProperties: false tags: - Shadows responses: '200': description: 'Success ' content: application/json: schema: description: 'The data that Shadows persists for each device. ' type: object properties: desired: description: 'The desired shadow of the device. ' type: object properties: payload: type: object description: 'A free format JSON object. The maximum size is 1000B. ' system: type: object description: 'Contains device configuration settings. ' properties: powerSave: description: Power save mode parameters. type: object properties: sendMs: description: The rate at which to send sample results in milliseconds in power save mode. A missing or zero value means power save mode is disabled. If present must be bigger than the value of `system.rate.sendMs`. type: number minimum: 0 rate: description: This can be used to specify the rates at which the device performs certain tasks. type: object properties: sampleMs: description: The rate at which to sample signals in milliseconds. Must be smaller than the value of `system.rate.sendMs`. type: number minimum: 0 sendMs: description: The rate at which to send sample results in milliseconds type: number minimum: 0 distanceM: description: Send an update if the device has moved farther than the specified distance in meters type: number minimum: 0 syncGeofences: description: A boolean value that sets efficient geofencing on or off type: boolean detectOutliers: description: A boolean value that sets outlier detection on or off type: boolean disableTracking: type: object description: 'Tracking can be disabled and enabled by defining disableTracking object. In order to disable tracking, one must at least provide the begin time of the disabling period and define either position or sensor properties one wants to disable. One can also disable both position and sensors at the same time. By default tracking is enabled. ' properties: periods: description: 'Define begin and end of the disabling period. All trace points with timestamp that falls between begin and end times will be disabled according to the settings defined in the position and sensors properties. ' type: array minItems: 0 maxItems: 1 title: Array of periods items: type: object properties: begin: type: integer description: 'Milliseconds elapsed since 1 January 1970 00:00:00 UTC Begin time of the tracking disabling period. Begin must be smaller than end. Begin must be greater or equal to current time. Begin can be set without end. If there exists already end time which is earlier than given new begin time, the existing end time will be deleted. ' minimum: 2 maximum: 4102448400000 end: type: integer description: 'Milliseconds elapsed since 1 January 1970 00:00:00 UTC End time of the tracking disabling period. End must be greater than begin. End must be greater or equal to current time. End can be set without begin if begin is already set. ' minimum: 2 maximum: 4102448400000 position: description: Define position methods to be disabled oneOf: - type: string title: all positioning enum: - all description: 'All positioning data the device sends will be removed before further processing. No geofence and location events will be generated ' - type: array minItems: 1 title: specified positioning methods items: type: string enum: - bt - country - gsm - wcdma - tdscdma - lte - cdma - wlan - gps description: 'The items specified in the position array will be removed from the ingestion scan object before further processing. Position may be resolved by the remaining scan properties. Some geofence and location events may be generated. ' - type: string title: re-enable enum: - '' description: 'By setting the position property empty string, all positioning data will be re-enabled during the disabling period. ' sensors: description: Define sensors to be disabled oneOf: - type: string enum: - all title: all sensors description: 'All sensor data the device sends will be removed before further processing. No sensor events will be generated. ' - type: array minItems: 1 title: specified sensors items: type: string enum: - accelerationG - deviceIsAttached - deviceIsStationary - batteryIsCharging - batteryLevel - pressureHpa - relativeHumidity - deviceIsTampered - temperatureC - tiltDegree description: 'The items specified in the sensors array will be removed from the ingestion system.reportedSensorData object before further processing. Sensor events will not be generated for the disabled sensors. ' - type: string title: re-enable enum: - '' description: 'By setting the sensors property empty string, all sensors data will be re-enabled during the disabling period. ' stateVersion: description: 'The version of the state of a device. This should be incremented only by HERE Tracking. ' type: integer minimum: 0 lastModifiedGeofenceTimestamp: description: 'Milliseconds elapsed since 1 January 1970 00:00:00 UTC. The time of the last update to geofences that device is associated with. This value is zero when device hasn''t yet been associated with any geofence. This is set by HERE Tracking when any geofences associated with the device is modified or removed. Also adding and removing geofence associations update this value. ' maximum: 4102448400000 minimum: 0 type: integer sensorAlarmConfig: description: 'The device sensors alarm configuration. ' type: object properties: alertTemperatureCMin: type: number description: A lower threshold value for temperature in degrees Celsius. alertTemperatureCMax: type: number description: An upper threshold value for temperature in degrees Celsius. alertRelativeHumidityMin: type: number description: A lower threshold value for relative humidity percentage. alertRelativeHumidityMax: type: number description: An upper threshold value for relative humidity percentage. alertAccelerationGMin: type: number description: A lower threshold value for acceleration in g-forces. alertAccelerationGMax: type: number description: An upper threshold value for acceleration in g-forces. alertTiltDegreeMin: type: number description: A lower threshold value for tilt in degrees. alertTiltDegreeMax: type: number description: An upper threshold value for tilt in degrees. alertPressureHpaMin: type: number description: A lower threshold value for pressure in hectopascals. alertPressureHpaMax: type: number description: An upper threshold value for pressure in hectopascals. alertBatteryLevelPMin: type: number description: A lower threshold value for battery level percentage. alertBatteryLevelPMax: type: number description: An upper threshold value for battery level percentage. isAttachAlertEnabled: type: boolean default: false description: True if attach sensor alert in device is enabled. isTamperAlertEnabled: type: boolean default: false description: True if tamper sensor alert in device is enabled. wlanConnectivityEnabled: description: A boolean value that sets wlan connectivity on or off type: boolean wlanConfigurations: description: An array of objects that holds wlan configurations type: array minItems: 0 maxItems: 10 items: type: object properties: securityMode: description: Selected security mode type: string enum: - none - wpa2psk ssid: description: Name given to a WLAN that is used by the client to access a WLAN network. Please note that the SSID is stored to the device unencrypted. Do not use secure private networks, such as Intranet, for tracker WLAN connectivity. type: string minLength: 1 maxLength: 32 password: description: WLAN password. Please note that the password is stored to the device unencrypted. Do not use secure private networks, such as Intranet, for tracker WLAN connectivity. Password is required if security mode is other then 'none'. type: string minLength: 8 maxLength: 63 ssidIsHidden: description: Flag that informs if SSID is hidden type: boolean additionalProperties: false required: - securityMode - ssid sensorLoggingEnabled: description: Flag that sets sensor logging on or off type: boolean sensorLoggingConfigurations: description: An array of objects that holds sensor logging configurations type: array minItems: 0 maxItems: 5 items: type: object properties: type: description: Type of single sensor logging configuration type: string enum: - acceleration - pressure - temperature - humidity - gnss samplingFrequency: description: Sampling frequrency of single sensor loggin configuration (in milliseconds) type: number minimum: 1 additionalProperties: false required: - type sensorLoggingTag: description: Tag for the logged sensor data. type: string minLength: 1 maxLength: 50 required: - stateVersion - lastModifiedGeofenceTimestamp timestamp: description: 'Milliseconds elapsed since 1 January 1970 00:00:00 UTC. The time of the last update to the desired shadow. ' maximum: 4102448400000 minimum: 2 type: integer reported: description: 'The `reported` shadow contains the most recent position, sensor readings and settings that the device has sent. The reported shadow may also contain additional properties generated by HERE Tracking based on the device-ingested telemetry. Such properties are stored in `system.computed` property of the shadow. In case the most recent telemetry did not contain all the possible fields, the last known information will remain in the shadow. This means that one can see, for example, the last reported temperature or tracker firmware information in the reported shadow, even if the device did not send that information in the latest telemetry. ' type: object properties: payload: type: object description: 'A free format JSON object. The maximum size is 1000B. ' position: type: object description: The device location properties: accuracy: description: Uncertainty circle radius in meters (degree of confidence according to the 'confidence' parameter). type: number minimum: 0 alt: description: Altitude in meters (referenced to the WGS-84 ellipsoid) negative or positive. type: number altaccuracy: description: Uncertainty of the altitude estimate in meters (degree of confidence according to the 'confidence' parameter). type: number minimum: 0 confidence: description: Confidence level in percent for the accuracy/uncertainty. If not specified, the default is 68 (this corresponds to a 68% probability that the true position is within the accuracy/uncertainty radius of the position; the higher the number, the greater the confidence level). type: integer minimum: 50 maximum: 95 heading: description: GPS/GNSS heading in degrees, clockwise from true north. You must specify a value for this item when you specify a value for speed. type: integer minimum: 0 maximum: 359 floor: description: The building where the measurements were taken type: object required: - id - name - level properties: level: description: The floor in the building in integer format type: number minimum: -999 maximum: 999 id: description: The building id type: string minimum: 1 maximum: 100 name: description: The building name type: string minimum: 1 maximum: 255 lat: description: Latitude in WGS-84 format, decimal representation ranging from -90 to 90. type: number minimum: -90 maximum: 90 lng: description: Longitude in WGS-84 format, decimal representation ranging from -180 to 180. type: number minimum: -180 maximum: 180 satellitecount: description: Number of GPS/GNSS satellites used for the calculation of the position fix. ('gnss' position type only) type: integer minimum: 1 maximum: 50 speed: description: GPS/GNSS speed of the device (m/s). One must specify a value for this item when one specifies a value for heading. type: integer minimum: 0 type: description: Position type, 'gnss' (satellite based), 'cell' or 'wlan' (network based) type: string wlancount: description: The total number of observed WLAN APs in the scan used for producing the position. ('wlan' position type only) type: integer minimum: 1 maximum: 254 timestamp: description: Timestamp of the position type: integer minimum: 2 maximum: 4102448400000 required: - lat - lng - accuracy system: allOf: - type: object properties: phoneNumber: type: string pattern: ^\+[1-9]\d{1,14}$ description: 'The phone number of the device''s SIM card in the international E.164 format. All the country codes should be prefixed a with "+" instead of "00". ' example: '+491234567890' imsi: type: string pattern: ^[0-9]{1,15}$ description: 'The IMSI of the device''s SIM card. ' example: '123456789012345' iccid: type: string minLength: 18 maxLength: 22 description: SIM card integrated circuit card identifier (ICCID) client: description: 'Information about the client device. ' type: object properties: manufacturer: description: Manufacturer of the device (hardware) type: string minLength: 2 maxLength: 50 model: description: Model of the device (hardware) type: string minLength: 1 maxLength: 50 firmware: description: Device firmware version information type: string minLength: 1 maxLength: 150 name: description: Name of the client software accessing the HERE API type: string minLength: 3 maxLength: 50 version: description: Version of the client software in format X.Y.Z, where X [0..255] is a major, Y [0..255] is a minor, and Z [0..65535] is a build version number. Increase the version/build number for each release of the client. type: string minLength: 3 maxLength: 60 platform: description: Software platform information of the device, for example operating system name and version. type: string minLength: 3 maxLength: 50 modules: description: Software information of all updateable chips. type: array maxItems: 10 items: description: Software information of an updateable chip. type: object properties: manufacturer: type: string description: Manufacturer name minLength: 2 maxLength: 50 model: type: string description: Model or chip name minLength: 1 maxLength: 50 firmwareVersion: type: string description: Installed firmware version minLength: 3 maxLength: 60 diskquota: description: Available disk quota in kilobytes. type: number minimum: 0 diagnosticscode: description: Device diagnostics code. type: number homenetwork: description: Information about subscriber home network - 3GPP MCC+MNC or 3GPP2 SID+NID. Dual-SIM devices can provide information on both subscriptions. type: array maxItems: 2 items: description: Network information. Either MCC + MNC or SID + NID attribute pair is required. type: object properties: mcc: description: Mobile Country Code type: integer minimum: 200 maximum: 999 mnc: description: Mobile Network Code type: integer minimum: 0 maximum: 999 sid: description: System Id, SID type: integer minimum: 1 maximum: 32767 nid: description: Network Id, NID type: integer minimum: 0 maximum: 65535 hasAttachSensor: type: boolean description: True if a device has a sensor to detect if the device is attached to or detached from an object. hasNoBattery: type: boolean description: False if a device has a battery. hasHumiditySensor: type: boolean description: True if a device has a sensor to measure humidity. hasPressureSensor: type: boolean description: True if a device has a sensor to measure pressure. hasTamperSensor: type: boolean description: True if a device has a sensor to detect if device is disassembled. hasTemperatureSensor: type: boolean description: True if a device has a sensor to measure temperature. hasAccelerometerSensor: type: boolean description: True if a device has a sensor to measure acceleration. accelerometerSensorRange: description: 'Specifies the range of measurable acceleration, representation unit g (9.8 m/s^2). If more than one accelerometer is available, each element in the list will represent individual accelerometer. Each value represents a single "+/-" range. For example, value 2 means that sensor is capable to measure acceleration within the range of [-2 g, +2 g]. ' type: array maxItems: 5 items: type: integer minimum: -1000 maximum: 1000 example: manufacturer: Samsung model: SM-G930F firmware: heroltexx... name: HERE Tracker version: 1.6.1 platform: Android diskquota: 256 diagnosticscode: 0 homenetwork: [] hasAttachSensor: true hasNoBattery: false hasHumiditySensor: true hasPressureSensor: true hasTamperSensor: true hasTemperatureSensor: true hasAccelerometerSensor: true accelerometerSensorRange: - 2 stateVersion: description: 'The version of the state of a device. This should be incremented only by HERE Tracking. ' type: integer minimum: 0 reportedSensorData: description: 'The last known device sensor data reported by the device. ' type: object properties: accelerationG: type: number description: A g-force value of acceleration. minimum: -100 maximum: 100 deviceIsAttached: type: boolean description: True if device is attached to an object. deviceIsStationary: type: boolean description: True if device hasn't detected movement. batteryIsCharging: type: boolean description: True if device battery is charging. batteryLevel: type: integer description: A value of percentage battery level. minimum: 0 maximum: 100 pressureHpa: type: number description: A value of pressure in hectopascal. minimum: 300 maximum: 1500 relativeHumidity: type: number description: A value of relative humidity in percent. minimum: 0 maximum: 100 deviceIsTampered: type: boolean description: True if device is tampered. temperatureC: type: number description: A value of temperature in celcius. minimum: -70 maximum: 100 tiltDegree: type: number description: A value of tilt in degrees. mode: description: 'Tracker mode status of the device. When a tracker is in normal mode, it can send telemetry and, for example, use its GNSS receiver if it has one. A tracker switches into flight mode once it detects that it''s in an airplane, and leaves that mode once the airplane lands. Transport mode has to be triggered by the user, and it''s used, for example, during shipping from continent to another. Sleep mode is used when a tracker is stored in a warehouse, and it''s triggered by entering or leaving some defined geofence. Power save mode can be enabled with `system.powerSave.sendMs` property in the desired shadow and when enabled the device enters power save mode when the device is not moving. ' type: string enum: - unknown - normal - flight - transport - sleep - powerSave description: 'Contains device-reported sensor data and device configuration settings. `stateVersion` property contains the version of the last known `desired` state seen by the device. ' - type: object properties: computed: description: Values computed by HERE Tracking based on other data available. properties: online: description: Online status of the device. Computed based on the device's reporting rate. If the device has not reported within the time frame of the reporting rate plus five minutes, the device is considered to be offline. If the reporting rate is not specified for the device, a default of 15 minutes is used. type: boolean moving: description: 'Asset is considered moving if the positions of two consecutive trace points differ more than the combined positioning accuracy + 100 meters. ' type: boolean lastMovedTimestamp: description: 'Timestamp referring to the trace point when the asset was last detected moving. Asset is considered moving if the positions of two consecutive trace points differ more than the combined positioning accuracy + 100 meters. ' type: integer outlier: description: 'Indicates that HERE Tracking detected position to be a possible outlier. ' type: object properties: reason: description: Reason why position was considered to be an outlier. type: string correctedPosition: description: HERE Tracking estimate of more correct position. type: object properties: accuracy: description: Uncertainty circle radius in meters (degree of confidence according to the 'confidence' parameter). type: number minimum: 0 lat: description: Latitude in WGS-84 format, decimal representation ranging from -90 to 90. type: number minimum: -90 maximum: 90 lng: description: Longitude in WGS-84 format, decimal representation ranging from -180 to 180. type: number minimum: -180 maximum: 180 timestamp: type: integer description: Milliseconds elapsed since 1 January 1970 00:00:00 UTC. minimum: 2 maximum: 4102448400000 required: - accuracy - lat - lng required: - reason timestamp: description: 'Milliseconds elapsed since 1 January 1970 00:00:00 UTC. The timestamp of the newest telemetry sent by the device. Note that this is not necessarily the timestamp of all the reported values in the reported shadow since the shadow retains values from previous ingestions if the latest telemetry did not conatain them. ' maximum: 4102448400000 minimum: 2 type: integer example: desired: payload: color: red system: stateVersion: 2 rate: sendMs: 300000 sampleMs: 300000 distanceM: 0 lastModifiedGeofenceTimestamp: 0 timestamp: 1461065261010 '400': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Bad request code: 400 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The request object is in an incorrect format or has values that are invalid or out of range. details: hereErrorCode: 400306 description: 'Bad request The request object is in an incorrect format or has values that are invalid or out of range. If available, further error details are provided in the response body. ' '401': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Unauthorized code: 401 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The provided credentials are not valid. details: hereErrorCode: 401306 description: 'Unauthorized The request did not provide correct authentication details ' '403': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Forbidden code: 403 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The account does not have the correct privileges. details: hereErrorCode: 403306 description: 'Forbidden The account does not have the correct privileges ' '404': description: Not found. Shadow doesn't exist. '409': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Conflict code: 409 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The specified resource already exists. details: hereErrorCode: 404306 description: 'Conflict The specified resource already exists ' '413': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Payload Too Large code: 413 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The request size exceeds the maximum size limit for payloads. details: hereErrorCode: 413306 description: 'Payload Too Large The request size exceeds the maximum size limit for payloads. ' operationId: putShadowsV2ByTrackingId x-operation-id-source: derived get: summary: Gets a device shadow description: '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.' security: - UserToken: [] - ClientToken: [] - DeviceToken: [] parameters: - name: trackingId in: path schema: type: string minLength: 1 maxLength: 50 description: This is a unique ID associated with the device data in HERE Tracking. The `trackingId` gets assigned to a device when the device is claimed by a user. Alternatively, a valid `shipmentId` may be used. required: true tags: - Shadows responses: '200': description: 'Successful The device shadow was successfully retrieved. ' content: application/json: schema: description: 'The data that Shadows persists for each device. ' type: object properties: desired: description: 'The desired shadow of the device. ' type: object properties: payload: type: object description: 'A free format JSON object. The maximum size is 1000B. ' system: type: object description: 'Contains device configuration settings. ' properties: powerSave: description: Power save mode parameters. type: object properties: sendMs: description: The rate at which to send sample results in milliseconds in power save mode. A missing or zero value means power save mode is disabled. If present must be bigger than the value of `system.rate.sendMs`. type: number minimum: 0 rate: description: This can be used to specify the rates at which the device performs certain tasks. type: object properties: sampleMs: description: The rate at which to sample signals in milliseconds. Must be smaller than the value of `system.rate.sendMs`. type: number minimum: 0 sendMs: description: The rate at which to send sample results in milliseconds type: number minimum: 0 distanceM: description: Send an update if the device has moved farther than the specified distance in meters type: number minimum: 0 syncGeofences: description: A boolean value that sets efficient geofencing on or off type: boolean detectOutliers: description: A boolean value that sets outlier detection on or off type: boolean disableTracking: type: object description: 'Tracking can be disabled and enabled by defining disableTracking object. In order to disable tracking, one must at least provide the begin time of the disabling period and define either position or sensor properties one wants to disable. One can also disable both position and sensors at the same time. By default tracking is enabled. ' properties: periods: description: 'Define begin and end of the disabling period. All trace points with timestamp that falls between begin and end times will be disabled according to the settings defined in the position and sensors properties. ' type: array minItems: 0 maxItems: 1 title: Array of periods items: type: object properties: begin: type: integer description: 'Milliseconds elapsed since 1 January 1970 00:00:00 UTC Begin time of the tracking disabling period. Begin must be smaller than end. Begin must be greater or equal to current time. Begin can be set without end. If there exists already end time which is earlier than given new begin time, the existing end time will be deleted. ' minimum: 2 maximum: 4102448400000 end: type: integer description: 'Milliseconds elapsed since 1 January 1970 00:00:00 UTC End time of the tracking disabling period. End must be greater than begin. End must be greater or equal to current time. End can be set without begin if begin is already set. ' minimum: 2 maximum: 4102448400000 position: description: Define position methods to be disabled oneOf: - type: string title: all positioning enum: - all description: 'All positioning data the device sends will be removed before further processing. No geofence and location events will be generated ' - type: array minItems: 1 title: specified positioning methods items: type: string enum: - bt - country - gsm - wcdma - tdscdma - lte - cdma - wlan - gps description: 'The items specified in the position array will be removed from the ingestion scan object before further processing. Position may be resolved by the remaining scan properties. Some geofence and location events may be generated. ' - type: string title: re-enable enum: - '' description: 'By setting the position property empty string, all positioning data will be re-enabled during the disabling period. ' sensors: description: Define sensors to be disabled oneOf: - type: string enum: - all title: all sensors description: 'All sensor data the device sends will be removed before further processing. No sensor events will be generated. ' - type: array minItems: 1 title: specified sensors items: type: string enum: - accelerationG - deviceIsAttached - deviceIsStationary - batteryIsCharging - batteryLevel - pressureHpa - relativeHumidity - deviceIsTampered - temperatureC - tiltDegree description: 'The items specified in the sensors array will be removed from the ingestion system.reportedSensorData object before further processing. Sensor events will not be generated for the disabled sensors. ' - type: string title: re-enable enum: - '' description: 'By setting the sensors property empty string, all sensors data will be re-enabled during the disabling period. ' stateVersion: description: 'The version of the state of a device. This should be incremented only by HERE Tracking. ' type: integer minimum: 0 lastModifiedGeofenceTimestamp: description: 'Milliseconds elapsed since 1 January 1970 00:00:00 UTC. The time of the last update to geofences that device is associated with. This value is zero when device hasn''t yet been associated with any geofence. This is set by HERE Tracking when any geofences associated with the device is modified or removed. Also adding and removing geofence associations update this value. ' maximum: 4102448400000 minimum: 0 type: integer sensorAlarmConfig: description: 'The device sensors alarm configuration. ' type: object properties: alertTemperatureCMin: type: number description: A lower threshold value for temperature in degrees Celsius. alertTemperatureCMax: type: number description: An upper threshold value for temperature in degrees Celsius. alertRelativeHumidityMin: type: number description: A lower threshold value for relative humidity percentage. alertRelativeHumidityMax: type: number description: An upper threshold value for relative humidity percentage. alertAccelerationGMin: type: number description: A lower threshold value for acceleration in g-forces. alertAccelerationGMax: type: number description: An upper threshold value for acceleration in g-forces. alertTiltDegreeMin: type: number description: A lower threshold value for tilt in degrees. alertTiltDegreeMax: type: number description: An upper threshold value for tilt in degrees. alertPressureHpaMin: type: number description: A lower threshold value for pressure in hectopascals. alertPressureHpaMax: type: number description: An upper threshold value for pressure in hectopascals. alertBatteryLevelPMin: type: number description: A lower threshold value for battery level percentage. alertBatteryLevelPMax: type: number description: An upper threshold value for battery level percentage. isAttachAlertEnabled: type: boolean default: false description: True if attach sensor alert in device is enabled. isTamperAlertEnabled: type: boolean default: false description: True if tamper sensor alert in device is enabled. wlanConnectivityEnabled: description: A boolean value that sets wlan connectivity on or off type: boolean wlanConfigurations: description: An array of objects that holds wlan configurations type: array minItems: 0 maxItems: 10 items: type: object properties: securityMode: description: Selected security mode type: string enum: - none - wpa2psk ssid: description: Name given to a WLAN that is used by the client to access a WLAN network. Please note that the SSID is stored to the device unencrypted. Do not use secure private networks, such as Intranet, for tracker WLAN connectivity. type: string minLength: 1 maxLength: 32 password: description: WLAN password. Please note that the password is stored to the device unencrypted. Do not use secure private networks, such as Intranet, for tracker WLAN connectivity. Password is required if security mode is other then 'none'. type: string minLength: 8 maxLength: 63 ssidIsHidden: description: Flag that informs if SSID is hidden type: boolean additionalProperties: false required: - securityMode - ssid sensorLoggingEnabled: description: Flag that sets sensor logging on or off type: boolean sensorLoggingConfigurations: description: An array of objects that holds sensor logging configurations type: array minItems: 0 maxItems: 5 items: type: object properties: type: description: Type of single sensor logging configuration type: string enum: - acceleration - pressure - temperature - humidity - gnss samplingFrequency: description: Sampling frequrency of single sensor loggin configuration (in milliseconds) type: number minimum: 1 additionalProperties: false required: - type sensorLoggingTag: description: Tag for the logged sensor data. type: string minLength: 1 maxLength: 50 required: - stateVersion - lastModifiedGeofenceTimestamp timestamp: description: 'Milliseconds elapsed since 1 January 1970 00:00:00 UTC. The time of the last update to the desired shadow. ' maximum: 4102448400000 minimum: 2 type: integer reported: description: 'The `reported` shadow contains the most recent position, sensor readings and settings that the device has sent. The reported shadow may also contain additional properties generated by HERE Tracking based on the device-ingested telemetry. Such properties are stored in `system.computed` property of the shadow. In case the most recent telemetry did not contain all the possible fields, the last known information will remain in the shadow. This means that one can see, for example, the last reported temperature or tracker firmware information in the reported shadow, even if the device did not send that information in the latest telemetry. ' type: object properties: payload: type: object description: 'A free format JSON object. The maximum size is 1000B. ' position: type: object description: The device location properties: accuracy: description: Uncertainty circle radius in meters (degree of confidence according to the 'confidence' parameter). type: number minimum: 0 alt: description: Altitude in meters (referenced to the WGS-84 ellipsoid) negative or positive. type: number altaccuracy: description: Uncertainty of the altitude estimate in meters (degree of confidence according to the 'confidence' parameter). type: number minimum: 0 confidence: description: Confidence level in percent for the accuracy/uncertainty. If not specified, the default is 68 (this corresponds to a 68% probability that the true position is within the accuracy/uncertainty radius of the position; the higher the number, the greater the confidence level). type: integer minimum: 50 maximum: 95 heading: description: GPS/GNSS heading in degrees, clockwise from true north. You must specify a value for this item when you specify a value for speed. type: integer minimum: 0 maximum: 359 floor: description: The building where the measurements were taken type: object required: - id - name - level properties: level: description: The floor in the building in integer format type: number minimum: -999 maximum: 999 id: description: The building id type: string minimum: 1 maximum: 100 name: description: The building name type: string minimum: 1 maximum: 255 lat: description: Latitude in WGS-84 format, decimal representation ranging from -90 to 90. type: number minimum: -90 maximum: 90 lng: description: Longitude in WGS-84 format, decimal representation ranging from -180 to 180. type: number minimum: -180 maximum: 180 satellitecount: description: Number of GPS/GNSS satellites used for the calculation of the position fix. ('gnss' position type only) type: integer minimum: 1 maximum: 50 speed: description: GPS/GNSS speed of the device (m/s). One must specify a value for this item when one specifies a value for heading. type: integer minimum: 0 type: description: Position type, 'gnss' (satellite based), 'cell' or 'wlan' (network based) type: string wlancount: description: The total number of observed WLAN APs in the scan used for producing the position. ('wlan' position type only) type: integer minimum: 1 maximum: 254 timestamp: description: Timestamp of the position type: integer minimum: 2 maximum: 4102448400000 required: - lat - lng - accuracy system: allOf: - type: object properties: phoneNumber: type: string pattern: ^\+[1-9]\d{1,14}$ description: 'The phone number of the device''s SIM card in the international E.164 format. All the country codes should be prefixed a with "+" instead of "00". ' example: '+491234567890' imsi: type: string pattern: ^[0-9]{1,15}$ description: 'The IMSI of the device''s SIM card. ' example: '123456789012345' iccid: type: string minLength: 18 maxLength: 22 description: SIM card integrated circuit card identifier (ICCID) client: description: 'Information about the client device. ' type: object properties: manufacturer: description: Manufacturer of the device (hardware) type: string minLength: 2 maxLength: 50 model: description: Model of the device (hardware) type: string minLength: 1 maxLength: 50 firmware: description: Device firmware version information type: string minLength: 1 maxLength: 150 name: description: Name of the client software accessing the HERE API type: string minLength: 3 maxLength: 50 version: description: Version of the client software in format X.Y.Z, where X [0..255] is a major, Y [0..255] is a minor, and Z [0..65535] is a build version number. Increase the version/build number for each release of the client. type: string minLength: 3 maxLength: 60 platform: description: Software platform information of the device, for example operating system name and version. type: string minLength: 3 maxLength: 50 modules: description: Software information of all updateable chips. type: array maxItems: 10 items: description: Software information of an updateable chip. type: object properties: manufacturer: type: string description: Manufacturer name minLength: 2 maxLength: 50 model: type: string description: Model or chip name minLength: 1 maxLength: 50 firmwareVersion: type: string description: Installed firmware version minLength: 3 maxLength: 60 diskquota: description: Available disk quota in kilobytes. type: number minimum: 0 diagnosticscode: description: Device diagnostics code. type: number homenetwork: description: Information about subscriber home network - 3GPP MCC+MNC or 3GPP2 SID+NID. Dual-SIM devices can provide information on both subscriptions. type: array maxItems: 2 items: description: Network information. Either MCC + MNC or SID + NID attribute pair is required. type: object properties: mcc: description: Mobile Country Code type: integer minimum: 200 maximum: 999 mnc: description: Mobile Network Code type: integer minimum: 0 maximum: 999 sid: description: System Id, SID type: integer minimum: 1 maximum: 32767 nid: description: Network Id, NID type: integer minimum: 0 maximum: 65535 hasAttachSensor: type: boolean description: True if a device has a sensor to detect if the device is attached to or detached from an object. hasNoBattery: type: boolean description: False if a device has a battery. hasHumiditySensor: type: boolean description: True if a device has a sensor to measure humidity. hasPressureSensor: type: boolean description: True if a device has a sensor to measure pressure. hasTamperSensor: type: boolean description: True if a device has a sensor to detect if device is disassembled. hasTemperatureSensor: type: boolean description: True if a device has a sensor to measure temperature. hasAccelerometerSensor: type: boolean description: True if a device has a sensor to measure acceleration. accelerometerSensorRange: description: 'Specifies the range of measurable acceleration, representation unit g (9.8 m/s^2). If more than one accelerometer is available, each element in the list will represent individual accelerometer. Each value represents a single "+/-" range. For example, value 2 means that sensor is capable to measure acceleration within the range of [-2 g, +2 g]. ' type: array maxItems: 5 items: type: integer minimum: -1000 maximum: 1000 example: manufacturer: Samsung model: SM-G930F firmware: heroltexx... name: HERE Tracker version: 1.6.1 platform: Android diskquota: 256 diagnosticscode: 0 homenetwork: [] hasAttachSensor: true hasNoBattery: false hasHumiditySensor: true hasPressureSensor: true hasTamperSensor: true hasTemperatureSensor: true hasAccelerometerSensor: true accelerometerSensorRange: - 2 stateVersion: description: 'The version of the state of a device. This should be incremented only by HERE Tracking. ' type: integer minimum: 0 reportedSensorData: description: 'The last known device sensor data reported by the device. ' type: object properties: accelerationG: type: number description: A g-force value of acceleration. minimum: -100 maximum: 100 deviceIsAttached: type: boolean description: True if device is attached to an object. deviceIsStationary: type: boolean description: True if device hasn't detected movement. batteryIsCharging: type: boolean description: True if device battery is charging. batteryLevel: type: integer description: A value of percentage battery level. minimum: 0 maximum: 100 pressureHpa: type: number description: A value of pressure in hectopascal. minimum: 300 maximum: 1500 relativeHumidity: type: number description: A value of relative humidity in percent. minimum: 0 maximum: 100 deviceIsTampered: type: boolean description: True if device is tampered. temperatureC: type: number description: A value of temperature in celcius. minimum: -70 maximum: 100 tiltDegree: type: number description: A value of tilt in degrees. mode: description: 'Tracker mode status of the device. When a tracker is in normal mode, it can send telemetry and, for example, use its GNSS receiver if it has one. A tracker switches into flight mode once it detects that it''s in an airplane, and leaves that mode once the airplane lands. Transport mode has to be triggered by the user, and it''s used, for example, during shipping from continent to another. Sleep mode is used when a tracker is stored in a warehouse, and it''s triggered by entering or leaving some defined geofence. Power save mode can be enabled with `system.powerSave.sendMs` property in the desired shadow and when enabled the device enters power save mode when the device is not moving. ' type: string enum: - unknown - normal - flight - transport - sleep - powerSave description: 'Contains device-reported sensor data and device configuration settings. `stateVersion` property contains the version of the last known `desired` state seen by the device. ' - type: object properties: computed: description: Values computed by HERE Tracking based on other data available. properties: online: description: Online status of the device. Computed based on the device's reporting rate. If the device has not reported within the time frame of the reporting rate plus five minutes, the device is considered to be offline. If the reporting rate is not specified for the device, a default of 15 minutes is used. type: boolean moving: description: 'Asset is considered moving if the positions of two consecutive trace points differ more than the combined positioning accuracy + 100 meters. ' type: boolean lastMovedTimestamp: description: 'Timestamp referring to the trace point when the asset was last detected moving. Asset is considered moving if the positions of two consecutive trace points differ more than the combined positioning accuracy + 100 meters. ' type: integer outlier: description: 'Indicates that HERE Tracking detected position to be a possible outlier. ' type: object properties: reason: description: Reason why position was considered to be an outlier. type: string correctedPosition: description: HERE Tracking estimate of more correct position. type: object properties: accuracy: description: Uncertainty circle radius in meters (degree of confidence according to the 'confidence' parameter). type: number minimum: 0 lat: description: Latitude in WGS-84 format, decimal representation ranging from -90 to 90. type: number minimum: -90 maximum: 90 lng: description: Longitude in WGS-84 format, decimal representation ranging from -180 to 180. type: number minimum: -180 maximum: 180 timestamp: type: integer description: Milliseconds elapsed since 1 January 1970 00:00:00 UTC. minimum: 2 maximum: 4102448400000 required: - accuracy - lat - lng required: - reason timestamp: description: 'Milliseconds elapsed since 1 January 1970 00:00:00 UTC. The timestamp of the newest telemetry sent by the device. Note that this is not necessarily the timestamp of all the reported values in the reported shadow since the shadow retains values from previous ingestions if the latest telemetry did not conatain them. ' maximum: 4102448400000 minimum: 2 type: integer example: reported: payload: color: blue velocity: 100 position: lat: 52.5 lng: 13.4 alt: 97 desired: payload: color: red velocity: 100 timestamp: 1461065261010 '400': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Bad request code: 400 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The request object is in an incorrect format or has values that are invalid or out of range. details: hereErrorCode: 400306 description: 'Bad request The request object is in an incorrect format or has values that are invalid or out of range. If available, further error details are provided in the response body. ' '401': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Unauthorized code: 401 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The provided credentials are not valid. details: hereErrorCode: 401306 description: 'Unauthorized The request did not provide correct authentication details ' '403': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Forbidden code: 403 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The account does not have the correct privileges. details: hereErrorCode: 403306 description: 'Forbidden The account does not have the correct privileges ' '404': description: Not found. No shadow exists for the requested trackingId. content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code id: type: string format: uuid description: An error ID that allows you to trace the error details message: type: string description: Descriptive text that explains the error details: description: An optional object containing more information about the error required: - error - code - id example: - error: Unauthorized code: 401 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee message: Invalid Authorization, the request lacks valid authentication credentials for the target resource. details: hereErrorCode: 401306 operationId: getShadowsV2ByTrackingId x-operation-id-source: derived delete: summary: Clears a device shadow description: '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.' security: - UserToken: [] - ClientToken: [] parameters: - name: trackingId in: path schema: type: string minLength: 1 maxLength: 50 description: This is a unique ID associated with the device data in HERE Tracking. The `trackingId` gets assigned to a device when the device is claimed by a user. required: true - name: desired in: query required: false description: If `true`, all the values of the `desired` shadow will be cleared schema: type: boolean default: true - name: reported in: query required: false description: If `true`, all the values of the `reported` shadow will be cleared schema: type: boolean default: true tags: - Shadows responses: '204': description: Successful (no content) '400': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Bad request code: 400 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The request object is in an incorrect format or has values that are invalid or out of range. details: hereErrorCode: 400306 description: 'Bad request The request object is in an incorrect format or has values that are invalid or out of range. If available, further error details are provided in the response body. ' '401': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Unauthorized code: 401 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The provided credentials are not valid. details: hereErrorCode: 401306 description: 'Unauthorized The request did not provide correct authentication details ' '403': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Forbidden code: 403 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The account does not have the correct privileges. details: hereErrorCode: 403306 description: 'Forbidden The account does not have the correct privileges ' '404': description: Not found. No shadow exists for the requested trackingId. content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code id: type: string format: uuid description: An error ID that allows you to trace the error details message: type: string description: Descriptive text that explains the error details: description: An optional object containing more information about the error required: - error - code - id example: - error: Unauthorized code: 401 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee message: Invalid Authorization, the request lacks valid authentication credentials for the target resource. details: hereErrorCode: 401306 operationId: deleteShadowsV2ByTrackingId x-operation-id-source: derived /shadows/v2/batch: post: summary: Gets a batch of device shadows description: '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.' security: - UserToken: [] - ClientToken: [] parameters: - in: header name: X-Request-Id schema: type: string format: uuid description: 'ID used for correlating requests within HERE Tracking. Used for logging and error reporting. Must be a valid UUIDv4. ' required: false - name: after description: 'Milliseconds elapsed since 1 January 1970 00:00:00 UTC. The accepted range is from 0 to the current time. ' in: query required: false schema: type: number minimum: 0 - name: appId description: Application identifier. Used together with an external ID to identify a virtual device. schema: type: string minLength: 8 in: query required: false requestBody: content: application/json: schema: type: array description: An array of trackingIds of devices minItems: 1 maxItems: 100 items: type: string minLength: 1 maxLength: 50 description: This is a unique ID associated with the device data in HERE Tracking. The `trackingId` gets assigned to a device when the device is claimed by a user. example: - HERE-6da0f871-b4eb-4800-90e6-4bae86a788d6 - HERE-b0146d7b-2e46-4cee-bc71-6da03ba2da85 tags: - Shadows responses: '200': description: 'Successful The response body contains a list of device shadows accompanied by statusCode and trackingId of the associated device. The returned shadow objects are in same order as the trackingIds provided in the request. In case of an error, each trackingId has a separate status code: * 403 - Forbidden * 404 - Device not found ' content: application/json: schema: type: array items: type: object properties: body: description: 'The data that Shadows persists for each device. ' type: object properties: desired: description: 'The desired shadow of the device. ' type: object properties: payload: type: object description: 'A free format JSON object. The maximum size is 1000B. ' system: type: object description: 'Contains device configuration settings. ' properties: powerSave: description: Power save mode parameters. type: object properties: sendMs: description: The rate at which to send sample results in milliseconds in power save mode. A missing or zero value means power save mode is disabled. If present must be bigger than the value of `system.rate.sendMs`. type: number minimum: 0 rate: description: This can be used to specify the rates at which the device performs certain tasks. type: object properties: sampleMs: description: The rate at which to sample signals in milliseconds. Must be smaller than the value of `system.rate.sendMs`. type: number minimum: 0 sendMs: description: The rate at which to send sample results in milliseconds type: number minimum: 0 distanceM: description: Send an update if the device has moved farther than the specified distance in meters type: number minimum: 0 syncGeofences: description: A boolean value that sets efficient geofencing on or off type: boolean detectOutliers: description: A boolean value that sets outlier detection on or off type: boolean disableTracking: type: object description: 'Tracking can be disabled and enabled by defining disableTracking object. In order to disable tracking, one must at least provide the begin time of the disabling period and define either position or sensor properties one wants to disable. One can also disable both position and sensors at the same time. By default tracking is enabled. ' properties: periods: description: 'Define begin and end of the disabling period. All trace points with timestamp that falls between begin and end times will be disabled according to the settings defined in the position and sensors properties. ' type: array minItems: 0 maxItems: 1 title: Array of periods items: type: object properties: begin: type: integer description: 'Milliseconds elapsed since 1 January 1970 00:00:00 UTC Begin time of the tracking disabling period. Begin must be smaller than end. Begin must be greater or equal to current time. Begin can be set without end. If there exists already end time which is earlier than given new begin time, the existing end time will be deleted. ' minimum: 2 maximum: 4102448400000 end: type: integer description: 'Milliseconds elapsed since 1 January 1970 00:00:00 UTC End time of the tracking disabling period. End must be greater than begin. End must be greater or equal to current time. End can be set without begin if begin is already set. ' minimum: 2 maximum: 4102448400000 position: description: Define position methods to be disabled oneOf: - type: string title: all positioning enum: - all description: 'All positioning data the device sends will be removed before further processing. No geofence and location events will be generated ' - type: array minItems: 1 title: specified positioning methods items: type: string enum: - bt - country - gsm - wcdma - tdscdma - lte - cdma - wlan - gps description: 'The items specified in the position array will be removed from the ingestion scan object before further processing. Position may be resolved by the remaining scan properties. Some geofence and location events may be generated. ' - type: string title: re-enable enum: - '' description: 'By setting the position property empty string, all positioning data will be re-enabled during the disabling period. ' sensors: description: Define sensors to be disabled oneOf: - type: string enum: - all title: all sensors description: 'All sensor data the device sends will be removed before further processing. No sensor events will be generated. ' - type: array minItems: 1 title: specified sensors items: type: string enum: - accelerationG - deviceIsAttached - deviceIsStationary - batteryIsCharging - batteryLevel - pressureHpa - relativeHumidity - deviceIsTampered - temperatureC - tiltDegree description: 'The items specified in the sensors array will be removed from the ingestion system.reportedSensorData object before further processing. Sensor events will not be generated for the disabled sensors. ' - type: string title: re-enable enum: - '' description: 'By setting the sensors property empty string, all sensors data will be re-enabled during the disabling period. ' stateVersion: description: 'The version of the state of a device. This should be incremented only by HERE Tracking. ' type: integer minimum: 0 lastModifiedGeofenceTimestamp: description: 'Milliseconds elapsed since 1 January 1970 00:00:00 UTC. The time of the last update to geofences that device is associated with. This value is zero when device hasn''t yet been associated with any geofence. This is set by HERE Tracking when any geofences associated with the device is modified or removed. Also adding and removing geofence associations update this value. ' maximum: 4102448400000 minimum: 0 type: integer sensorAlarmConfig: description: 'The device sensors alarm configuration. ' type: object properties: alertTemperatureCMin: type: number description: A lower threshold value for temperature in degrees Celsius. alertTemperatureCMax: type: number description: An upper threshold value for temperature in degrees Celsius. alertRelativeHumidityMin: type: number description: A lower threshold value for relative humidity percentage. alertRelativeHumidityMax: type: number description: An upper threshold value for relative humidity percentage. alertAccelerationGMin: type: number description: A lower threshold value for acceleration in g-forces. alertAccelerationGMax: type: number description: An upper threshold value for acceleration in g-forces. alertTiltDegreeMin: type: number description: A lower threshold value for tilt in degrees. alertTiltDegreeMax: type: number description: An upper threshold value for tilt in degrees. alertPressureHpaMin: type: number description: A lower threshold value for pressure in hectopascals. alertPressureHpaMax: type: number description: An upper threshold value for pressure in hectopascals. alertBatteryLevelPMin: type: number description: A lower threshold value for battery level percentage. alertBatteryLevelPMax: type: number description: An upper threshold value for battery level percentage. isAttachAlertEnabled: type: boolean default: false description: True if attach sensor alert in device is enabled. isTamperAlertEnabled: type: boolean default: false description: True if tamper sensor alert in device is enabled. wlanConnectivityEnabled: description: A boolean value that sets wlan connectivity on or off type: boolean wlanConfigurations: description: An array of objects that holds wlan configurations type: array minItems: 0 maxItems: 10 items: type: object properties: securityMode: description: Selected security mode type: string enum: - none - wpa2psk ssid: description: Name given to a WLAN that is used by the client to access a WLAN network. Please note that the SSID is stored to the device unencrypted. Do not use secure private networks, such as Intranet, for tracker WLAN connectivity. type: string minLength: 1 maxLength: 32 password: description: WLAN password. Please note that the password is stored to the device unencrypted. Do not use secure private networks, such as Intranet, for tracker WLAN connectivity. Password is required if security mode is other then 'none'. type: string minLength: 8 maxLength: 63 ssidIsHidden: description: Flag that informs if SSID is hidden type: boolean additionalProperties: false required: - securityMode - ssid sensorLoggingEnabled: description: Flag that sets sensor logging on or off type: boolean sensorLoggingConfigurations: description: An array of objects that holds sensor logging configurations type: array minItems: 0 maxItems: 5 items: type: object properties: type: description: Type of single sensor logging configuration type: string enum: - acceleration - pressure - temperature - humidity - gnss samplingFrequency: description: Sampling frequrency of single sensor loggin configuration (in milliseconds) type: number minimum: 1 additionalProperties: false required: - type sensorLoggingTag: description: Tag for the logged sensor data. type: string minLength: 1 maxLength: 50 required: - stateVersion - lastModifiedGeofenceTimestamp timestamp: description: 'Milliseconds elapsed since 1 January 1970 00:00:00 UTC. The time of the last update to the desired shadow. ' maximum: 4102448400000 minimum: 2 type: integer reported: description: 'The `reported` shadow contains the most recent position, sensor readings and settings that the device has sent. The reported shadow may also contain additional properties generated by HERE Tracking based on the device-ingested telemetry. Such properties are stored in `system.computed` property of the shadow. In case the most recent telemetry did not contain all the possible fields, the last known information will remain in the shadow. This means that one can see, for example, the last reported temperature or tracker firmware information in the reported shadow, even if the device did not send that information in the latest telemetry. ' type: object properties: payload: type: object description: 'A free format JSON object. The maximum size is 1000B. ' position: type: object description: The device location properties: accuracy: description: Uncertainty circle radius in meters (degree of confidence according to the 'confidence' parameter). type: number minimum: 0 alt: description: Altitude in meters (referenced to the WGS-84 ellipsoid) negative or positive. type: number altaccuracy: description: Uncertainty of the altitude estimate in meters (degree of confidence according to the 'confidence' parameter). type: number minimum: 0 confidence: description: Confidence level in percent for the accuracy/uncertainty. If not specified, the default is 68 (this corresponds to a 68% probability that the true position is within the accuracy/uncertainty radius of the position; the higher the number, the greater the confidence level). type: integer minimum: 50 maximum: 95 heading: description: GPS/GNSS heading in degrees, clockwise from true north. You must specify a value for this item when you specify a value for speed. type: integer minimum: 0 maximum: 359 floor: description: The building where the measurements were taken type: object required: - id - name - level properties: level: description: The floor in the building in integer format type: number minimum: -999 maximum: 999 id: description: The building id type: string minimum: 1 maximum: 100 name: description: The building name type: string minimum: 1 maximum: 255 lat: description: Latitude in WGS-84 format, decimal representation ranging from -90 to 90. type: number minimum: -90 maximum: 90 lng: description: Longitude in WGS-84 format, decimal representation ranging from -180 to 180. type: number minimum: -180 maximum: 180 satellitecount: description: Number of GPS/GNSS satellites used for the calculation of the position fix. ('gnss' position type only) type: integer minimum: 1 maximum: 50 speed: description: GPS/GNSS speed of the device (m/s). One must specify a value for this item when one specifies a value for heading. type: integer minimum: 0 type: description: Position type, 'gnss' (satellite based), 'cell' or 'wlan' (network based) type: string wlancount: description: The total number of observed WLAN APs in the scan used for producing the position. ('wlan' position type only) type: integer minimum: 1 maximum: 254 timestamp: description: Timestamp of the position type: integer minimum: 2 maximum: 4102448400000 required: - lat - lng - accuracy system: allOf: - type: object properties: phoneNumber: type: string pattern: ^\+[1-9]\d{1,14}$ description: 'The phone number of the device''s SIM card in the international E.164 format. All the country codes should be prefixed a with "+" instead of "00". ' example: '+491234567890' imsi: type: string pattern: ^[0-9]{1,15}$ description: 'The IMSI of the device''s SIM card. ' example: '123456789012345' iccid: type: string minLength: 18 maxLength: 22 description: SIM card integrated circuit card identifier (ICCID) client: description: 'Information about the client device. ' type: object properties: manufacturer: description: Manufacturer of the device (hardware) type: string minLength: 2 maxLength: 50 model: description: Model of the device (hardware) type: string minLength: 1 maxLength: 50 firmware: description: Device firmware version information type: string minLength: 1 maxLength: 150 name: description: Name of the client software accessing the HERE API type: string minLength: 3 maxLength: 50 version: description: Version of the client software in format X.Y.Z, where X [0..255] is a major, Y [0..255] is a minor, and Z [0..65535] is a build version number. Increase the version/build number for each release of the client. type: string minLength: 3 maxLength: 60 platform: description: Software platform information of the device, for example operating system name and version. type: string minLength: 3 maxLength: 50 modules: description: Software information of all updateable chips. type: array maxItems: 10 items: description: Software information of an updateable chip. type: object properties: manufacturer: type: string description: Manufacturer name minLength: 2 maxLength: 50 model: type: string description: Model or chip name minLength: 1 maxLength: 50 firmwareVersion: type: string description: Installed firmware version minLength: 3 maxLength: 60 diskquota: description: Available disk quota in kilobytes. type: number minimum: 0 diagnosticscode: description: Device diagnostics code. type: number homenetwork: description: Information about subscriber home network - 3GPP MCC+MNC or 3GPP2 SID+NID. Dual-SIM devices can provide information on both subscriptions. type: array maxItems: 2 items: description: Network information. Either MCC + MNC or SID + NID attribute pair is required. type: object properties: mcc: description: Mobile Country Code type: integer minimum: 200 maximum: 999 mnc: description: Mobile Network Code type: integer minimum: 0 maximum: 999 sid: description: System Id, SID type: integer minimum: 1 maximum: 32767 nid: description: Network Id, NID type: integer minimum: 0 maximum: 65535 hasAttachSensor: type: boolean description: True if a device has a sensor to detect if the device is attached to or detached from an object. hasNoBattery: type: boolean description: False if a device has a battery. hasHumiditySensor: type: boolean description: True if a device has a sensor to measure humidity. hasPressureSensor: type: boolean description: True if a device has a sensor to measure pressure. hasTamperSensor: type: boolean description: True if a device has a sensor to detect if device is disassembled. hasTemperatureSensor: type: boolean description: True if a device has a sensor to measure temperature. hasAccelerometerSensor: type: boolean description: True if a device has a sensor to measure acceleration. accelerometerSensorRange: description: 'Specifies the range of measurable acceleration, representation unit g (9.8 m/s^2). If more than one accelerometer is available, each element in the list will represent individual accelerometer. Each value represents a single "+/-" range. For example, value 2 means that sensor is capable to measure acceleration within the range of [-2 g, +2 g]. ' type: array maxItems: 5 items: type: integer minimum: -1000 maximum: 1000 example: manufacturer: Samsung model: SM-G930F firmware: heroltexx... name: HERE Tracker version: 1.6.1 platform: Android diskquota: 256 diagnosticscode: 0 homenetwork: [] hasAttachSensor: true hasNoBattery: false hasHumiditySensor: true hasPressureSensor: true hasTamperSensor: true hasTemperatureSensor: true hasAccelerometerSensor: true accelerometerSensorRange: - 2 stateVersion: description: 'The version of the state of a device. This should be incremented only by HERE Tracking. ' type: integer minimum: 0 reportedSensorData: description: 'The last known device sensor data reported by the device. ' type: object properties: accelerationG: type: number description: A g-force value of acceleration. minimum: -100 maximum: 100 deviceIsAttached: type: boolean description: True if device is attached to an object. deviceIsStationary: type: boolean description: True if device hasn't detected movement. batteryIsCharging: type: boolean description: True if device battery is charging. batteryLevel: type: integer description: A value of percentage battery level. minimum: 0 maximum: 100 pressureHpa: type: number description: A value of pressure in hectopascal. minimum: 300 maximum: 1500 relativeHumidity: type: number description: A value of relative humidity in percent. minimum: 0 maximum: 100 deviceIsTampered: type: boolean description: True if device is tampered. temperatureC: type: number description: A value of temperature in celcius. minimum: -70 maximum: 100 tiltDegree: type: number description: A value of tilt in degrees. mode: description: 'Tracker mode status of the device. When a tracker is in normal mode, it can send telemetry and, for example, use its GNSS receiver if it has one. A tracker switches into flight mode once it detects that it''s in an airplane, and leaves that mode once the airplane lands. Transport mode has to be triggered by the user, and it''s used, for example, during shipping from continent to another. Sleep mode is used when a tracker is stored in a warehouse, and it''s triggered by entering or leaving some defined geofence. Power save mode can be enabled with `system.powerSave.sendMs` property in the desired shadow and when enabled the device enters power save mode when the device is not moving. ' type: string enum: - unknown - normal - flight - transport - sleep - powerSave description: 'Contains device-reported sensor data and device configuration settings. `stateVersion` property contains the version of the last known `desired` state seen by the device. ' - type: object properties: computed: description: Values computed by HERE Tracking based on other data available. properties: online: description: Online status of the device. Computed based on the device's reporting rate. If the device has not reported within the time frame of the reporting rate plus five minutes, the device is considered to be offline. If the reporting rate is not specified for the device, a default of 15 minutes is used. type: boolean moving: description: 'Asset is considered moving if the positions of two consecutive trace points differ more than the combined positioning accuracy + 100 meters. ' type: boolean lastMovedTimestamp: description: 'Timestamp referring to the trace point when the asset was last detected moving. Asset is considered moving if the positions of two consecutive trace points differ more than the combined positioning accuracy + 100 meters. ' type: integer outlier: description: 'Indicates that HERE Tracking detected position to be a possible outlier. ' type: object properties: reason: description: Reason why position was considered to be an outlier. type: string correctedPosition: description: HERE Tracking estimate of more correct position. type: object properties: accuracy: description: Uncertainty circle radius in meters (degree of confidence according to the 'confidence' parameter). type: number minimum: 0 lat: description: Latitude in WGS-84 format, decimal representation ranging from -90 to 90. type: number minimum: -90 maximum: 90 lng: description: Longitude in WGS-84 format, decimal representation ranging from -180 to 180. type: number minimum: -180 maximum: 180 timestamp: type: integer description: Milliseconds elapsed since 1 January 1970 00:00:00 UTC. minimum: 2 maximum: 4102448400000 required: - accuracy - lat - lng required: - reason timestamp: description: 'Milliseconds elapsed since 1 January 1970 00:00:00 UTC. The timestamp of the newest telemetry sent by the device. Note that this is not necessarily the timestamp of all the reported values in the reported shadow since the shadow retains values from previous ingestions if the latest telemetry did not conatain them. ' maximum: 4102448400000 minimum: 2 type: integer statusCode: type: integer trackingId: type: string minLength: 1 maxLength: 50 description: This is a unique ID associated with the device data in HERE Tracking. The `trackingId` gets assigned to a device when the device is claimed by a user. appId: type: string minLength: 8 description: Virtual device application ID, only present when the device is virtual externalId: type: string minLength: 1 maxLength: 50 description: Virtual device external ID, only present when the device is virtual example: - body: desired: {} reported: position: lat: 40 lng: 30.2 accuracy: 30 system: phoneNumber: '+4917012345' statusCode: 200 trackingId: HERE-6da0f871-b4eb-4800-90e6-4bae86a788d6 - statusCode: 404 trackingId: HERE-b0146d7b-2e46-4cee-bc71-6da03ba2da85 '400': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Bad request code: 400 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The request object is in an incorrect format or has values that are invalid or out of range. details: hereErrorCode: 400306 description: 'Bad request The request object is in an incorrect format or has values that are invalid or out of range. If available, further error details are provided in the response body. ' '401': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Unauthorized code: 401 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The provided credentials are not valid. details: hereErrorCode: 401306 description: 'Unauthorized The request did not provide correct authentication details ' '403': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Forbidden code: 403 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The account does not have the correct privileges. details: hereErrorCode: 403306 description: 'Forbidden The account does not have the correct privileges ' operationId: postShadowsV2Batch x-operation-id-source: derived /shadows/v2/{trackingId}/{state}: parameters: - in: header name: X-Request-Id schema: type: string format: uuid description: 'ID used for correlating requests within HERE Tracking. Used for logging and error reporting. Must be a valid UUIDv4. ' required: false - name: trackingId in: path schema: type: string minLength: 1 maxLength: 50 description: This is a unique ID associated with the device data in HERE Tracking. The `trackingId` gets assigned to a device when the device is claimed by a user. Alternatively, a valid `shipmentId` may be used. required: true - name: appId description: Application identifier. Used together with an external ID to identify a virtual device. schema: type: string minLength: 8 in: query required: false - name: state in: path required: true description: Desired or reported state object of a device to query. schema: type: string enum: - desired - reported get: summary: Gets reported or desired state object of a device description: Gets the `reported` or `desired` state object of the device `trackingId`, that is the `reported` or `desired` device shadow. security: - UserToken: [] - ClientToken: [] - DeviceToken: [] tags: - Shadows responses: '200': description: 'Successful The requested device desired or reported state object ' content: application/json: schema: anyOf: - description: 'The desired shadow of the device. ' type: object properties: payload: type: object description: 'A free format JSON object. The maximum size is 1000B. ' system: type: object description: 'Contains device configuration settings. ' properties: powerSave: description: Power save mode parameters. type: object properties: sendMs: description: The rate at which to send sample results in milliseconds in power save mode. A missing or zero value means power save mode is disabled. If present must be bigger than the value of `system.rate.sendMs`. type: number minimum: 0 rate: description: This can be used to specify the rates at which the device performs certain tasks. type: object properties: sampleMs: description: The rate at which to sample signals in milliseconds. Must be smaller than the value of `system.rate.sendMs`. type: number minimum: 0 sendMs: description: The rate at which to send sample results in milliseconds type: number minimum: 0 distanceM: description: Send an update if the device has moved farther than the specified distance in meters type: number minimum: 0 syncGeofences: description: A boolean value that sets efficient geofencing on or off type: boolean detectOutliers: description: A boolean value that sets outlier detection on or off type: boolean disableTracking: type: object description: 'Tracking can be disabled and enabled by defining disableTracking object. In order to disable tracking, one must at least provide the begin time of the disabling period and define either position or sensor properties one wants to disable. One can also disable both position and sensors at the same time. By default tracking is enabled. ' properties: periods: description: 'Define begin and end of the disabling period. All trace points with timestamp that falls between begin and end times will be disabled according to the settings defined in the position and sensors properties. ' type: array minItems: 0 maxItems: 1 title: Array of periods items: type: object properties: begin: type: integer description: 'Milliseconds elapsed since 1 January 1970 00:00:00 UTC Begin time of the tracking disabling period. Begin must be smaller than end. Begin must be greater or equal to current time. Begin can be set without end. If there exists already end time which is earlier than given new begin time, the existing end time will be deleted. ' minimum: 2 maximum: 4102448400000 end: type: integer description: 'Milliseconds elapsed since 1 January 1970 00:00:00 UTC End time of the tracking disabling period. End must be greater than begin. End must be greater or equal to current time. End can be set without begin if begin is already set. ' minimum: 2 maximum: 4102448400000 position: description: Define position methods to be disabled oneOf: - type: string title: all positioning enum: - all description: 'All positioning data the device sends will be removed before further processing. No geofence and location events will be generated ' - type: array minItems: 1 title: specified positioning methods items: type: string enum: - bt - country - gsm - wcdma - tdscdma - lte - cdma - wlan - gps description: 'The items specified in the position array will be removed from the ingestion scan object before further processing. Position may be resolved by the remaining scan properties. Some geofence and location events may be generated. ' - type: string title: re-enable enum: - '' description: 'By setting the position property empty string, all positioning data will be re-enabled during the disabling period. ' sensors: description: Define sensors to be disabled oneOf: - type: string enum: - all title: all sensors description: 'All sensor data the device sends will be removed before further processing. No sensor events will be generated. ' - type: array minItems: 1 title: specified sensors items: type: string enum: - accelerationG - deviceIsAttached - deviceIsStationary - batteryIsCharging - batteryLevel - pressureHpa - relativeHumidity - deviceIsTampered - temperatureC - tiltDegree description: 'The items specified in the sensors array will be removed from the ingestion system.reportedSensorData object before further processing. Sensor events will not be generated for the disabled sensors. ' - type: string title: re-enable enum: - '' description: 'By setting the sensors property empty string, all sensors data will be re-enabled during the disabling period. ' stateVersion: description: 'The version of the state of a device. This should be incremented only by HERE Tracking. ' type: integer minimum: 0 lastModifiedGeofenceTimestamp: description: 'Milliseconds elapsed since 1 January 1970 00:00:00 UTC. The time of the last update to geofences that device is associated with. This value is zero when device hasn''t yet been associated with any geofence. This is set by HERE Tracking when any geofences associated with the device is modified or removed. Also adding and removing geofence associations update this value. ' maximum: 4102448400000 minimum: 0 type: integer sensorAlarmConfig: description: 'The device sensors alarm configuration. ' type: object properties: alertTemperatureCMin: type: number description: A lower threshold value for temperature in degrees Celsius. alertTemperatureCMax: type: number description: An upper threshold value for temperature in degrees Celsius. alertRelativeHumidityMin: type: number description: A lower threshold value for relative humidity percentage. alertRelativeHumidityMax: type: number description: An upper threshold value for relative humidity percentage. alertAccelerationGMin: type: number description: A lower threshold value for acceleration in g-forces. alertAccelerationGMax: type: number description: An upper threshold value for acceleration in g-forces. alertTiltDegreeMin: type: number description: A lower threshold value for tilt in degrees. alertTiltDegreeMax: type: number description: An upper threshold value for tilt in degrees. alertPressureHpaMin: type: number description: A lower threshold value for pressure in hectopascals. alertPressureHpaMax: type: number description: An upper threshold value for pressure in hectopascals. alertBatteryLevelPMin: type: number description: A lower threshold value for battery level percentage. alertBatteryLevelPMax: type: number description: An upper threshold value for battery level percentage. isAttachAlertEnabled: type: boolean default: false description: True if attach sensor alert in device is enabled. isTamperAlertEnabled: type: boolean default: false description: True if tamper sensor alert in device is enabled. wlanConnectivityEnabled: description: A boolean value that sets wlan connectivity on or off type: boolean wlanConfigurations: description: An array of objects that holds wlan configurations type: array minItems: 0 maxItems: 10 items: type: object properties: securityMode: description: Selected security mode type: string enum: - none - wpa2psk ssid: description: Name given to a WLAN that is used by the client to access a WLAN network. Please note that the SSID is stored to the device unencrypted. Do not use secure private networks, such as Intranet, for tracker WLAN connectivity. type: string minLength: 1 maxLength: 32 password: description: WLAN password. Please note that the password is stored to the device unencrypted. Do not use secure private networks, such as Intranet, for tracker WLAN connectivity. Password is required if security mode is other then 'none'. type: string minLength: 8 maxLength: 63 ssidIsHidden: description: Flag that informs if SSID is hidden type: boolean additionalProperties: false required: - securityMode - ssid sensorLoggingEnabled: description: Flag that sets sensor logging on or off type: boolean sensorLoggingConfigurations: description: An array of objects that holds sensor logging configurations type: array minItems: 0 maxItems: 5 items: type: object properties: type: description: Type of single sensor logging configuration type: string enum: - acceleration - pressure - temperature - humidity - gnss samplingFrequency: description: Sampling frequrency of single sensor loggin configuration (in milliseconds) type: number minimum: 1 additionalProperties: false required: - type sensorLoggingTag: description: Tag for the logged sensor data. type: string minLength: 1 maxLength: 50 required: - stateVersion - lastModifiedGeofenceTimestamp timestamp: description: 'Milliseconds elapsed since 1 January 1970 00:00:00 UTC. The time of the last update to the desired shadow. ' maximum: 4102448400000 minimum: 2 type: integer title: desired - description: 'The `reported` shadow contains the most recent position, sensor readings and settings that the device has sent. The reported shadow may also contain additional properties generated by HERE Tracking based on the device-ingested telemetry. Such properties are stored in `system.computed` property of the shadow. In case the most recent telemetry did not contain all the possible fields, the last known information will remain in the shadow. This means that one can see, for example, the last reported temperature or tracker firmware information in the reported shadow, even if the device did not send that information in the latest telemetry. ' type: object properties: payload: type: object description: 'A free format JSON object. The maximum size is 1000B. ' position: type: object description: The device location properties: accuracy: description: Uncertainty circle radius in meters (degree of confidence according to the 'confidence' parameter). type: number minimum: 0 alt: description: Altitude in meters (referenced to the WGS-84 ellipsoid) negative or positive. type: number altaccuracy: description: Uncertainty of the altitude estimate in meters (degree of confidence according to the 'confidence' parameter). type: number minimum: 0 confidence: description: Confidence level in percent for the accuracy/uncertainty. If not specified, the default is 68 (this corresponds to a 68% probability that the true position is within the accuracy/uncertainty radius of the position; the higher the number, the greater the confidence level). type: integer minimum: 50 maximum: 95 heading: description: GPS/GNSS heading in degrees, clockwise from true north. You must specify a value for this item when you specify a value for speed. type: integer minimum: 0 maximum: 359 floor: description: The building where the measurements were taken type: object required: - id - name - level properties: level: description: The floor in the building in integer format type: number minimum: -999 maximum: 999 id: description: The building id type: string minimum: 1 maximum: 100 name: description: The building name type: string minimum: 1 maximum: 255 lat: description: Latitude in WGS-84 format, decimal representation ranging from -90 to 90. type: number minimum: -90 maximum: 90 lng: description: Longitude in WGS-84 format, decimal representation ranging from -180 to 180. type: number minimum: -180 maximum: 180 satellitecount: description: Number of GPS/GNSS satellites used for the calculation of the position fix. ('gnss' position type only) type: integer minimum: 1 maximum: 50 speed: description: GPS/GNSS speed of the device (m/s). One must specify a value for this item when one specifies a value for heading. type: integer minimum: 0 type: description: Position type, 'gnss' (satellite based), 'cell' or 'wlan' (network based) type: string wlancount: description: The total number of observed WLAN APs in the scan used for producing the position. ('wlan' position type only) type: integer minimum: 1 maximum: 254 timestamp: description: Timestamp of the position type: integer minimum: 2 maximum: 4102448400000 required: - lat - lng - accuracy system: allOf: - type: object properties: phoneNumber: type: string pattern: ^\+[1-9]\d{1,14}$ description: 'The phone number of the device''s SIM card in the international E.164 format. All the country codes should be prefixed a with "+" instead of "00". ' example: '+491234567890' imsi: type: string pattern: ^[0-9]{1,15}$ description: 'The IMSI of the device''s SIM card. ' example: '123456789012345' iccid: type: string minLength: 18 maxLength: 22 description: SIM card integrated circuit card identifier (ICCID) client: description: 'Information about the client device. ' type: object properties: manufacturer: description: Manufacturer of the device (hardware) type: string minLength: 2 maxLength: 50 model: description: Model of the device (hardware) type: string minLength: 1 maxLength: 50 firmware: description: Device firmware version information type: string minLength: 1 maxLength: 150 name: description: Name of the client software accessing the HERE API type: string minLength: 3 maxLength: 50 version: description: Version of the client software in format X.Y.Z, where X [0..255] is a major, Y [0..255] is a minor, and Z [0..65535] is a build version number. Increase the version/build number for each release of the client. type: string minLength: 3 maxLength: 60 platform: description: Software platform information of the device, for example operating system name and version. type: string minLength: 3 maxLength: 50 modules: description: Software information of all updateable chips. type: array maxItems: 10 items: description: Software information of an updateable chip. type: object properties: manufacturer: type: string description: Manufacturer name minLength: 2 maxLength: 50 model: type: string description: Model or chip name minLength: 1 maxLength: 50 firmwareVersion: type: string description: Installed firmware version minLength: 3 maxLength: 60 diskquota: description: Available disk quota in kilobytes. type: number minimum: 0 diagnosticscode: description: Device diagnostics code. type: number homenetwork: description: Information about subscriber home network - 3GPP MCC+MNC or 3GPP2 SID+NID. Dual-SIM devices can provide information on both subscriptions. type: array maxItems: 2 items: description: Network information. Either MCC + MNC or SID + NID attribute pair is required. type: object properties: mcc: description: Mobile Country Code type: integer minimum: 200 maximum: 999 mnc: description: Mobile Network Code type: integer minimum: 0 maximum: 999 sid: description: System Id, SID type: integer minimum: 1 maximum: 32767 nid: description: Network Id, NID type: integer minimum: 0 maximum: 65535 hasAttachSensor: type: boolean description: True if a device has a sensor to detect if the device is attached to or detached from an object. hasNoBattery: type: boolean description: False if a device has a battery. hasHumiditySensor: type: boolean description: True if a device has a sensor to measure humidity. hasPressureSensor: type: boolean description: True if a device has a sensor to measure pressure. hasTamperSensor: type: boolean description: True if a device has a sensor to detect if device is disassembled. hasTemperatureSensor: type: boolean description: True if a device has a sensor to measure temperature. hasAccelerometerSensor: type: boolean description: True if a device has a sensor to measure acceleration. accelerometerSensorRange: description: 'Specifies the range of measurable acceleration, representation unit g (9.8 m/s^2). If more than one accelerometer is available, each element in the list will represent individual accelerometer. Each value represents a single "+/-" range. For example, value 2 means that sensor is capable to measure acceleration within the range of [-2 g, +2 g]. ' type: array maxItems: 5 items: type: integer minimum: -1000 maximum: 1000 example: manufacturer: Samsung model: SM-G930F firmware: heroltexx... name: HERE Tracker version: 1.6.1 platform: Android diskquota: 256 diagnosticscode: 0 homenetwork: [] hasAttachSensor: true hasNoBattery: false hasHumiditySensor: true hasPressureSensor: true hasTamperSensor: true hasTemperatureSensor: true hasAccelerometerSensor: true accelerometerSensorRange: - 2 stateVersion: description: 'The version of the state of a device. This should be incremented only by HERE Tracking. ' type: integer minimum: 0 reportedSensorData: description: 'The last known device sensor data reported by the device. ' type: object properties: accelerationG: type: number description: A g-force value of acceleration. minimum: -100 maximum: 100 deviceIsAttached: type: boolean description: True if device is attached to an object. deviceIsStationary: type: boolean description: True if device hasn't detected movement. batteryIsCharging: type: boolean description: True if device battery is charging. batteryLevel: type: integer description: A value of percentage battery level. minimum: 0 maximum: 100 pressureHpa: type: number description: A value of pressure in hectopascal. minimum: 300 maximum: 1500 relativeHumidity: type: number description: A value of relative humidity in percent. minimum: 0 maximum: 100 deviceIsTampered: type: boolean description: True if device is tampered. temperatureC: type: number description: A value of temperature in celcius. minimum: -70 maximum: 100 tiltDegree: type: number description: A value of tilt in degrees. mode: description: 'Tracker mode status of the device. When a tracker is in normal mode, it can send telemetry and, for example, use its GNSS receiver if it has one. A tracker switches into flight mode once it detects that it''s in an airplane, and leaves that mode once the airplane lands. Transport mode has to be triggered by the user, and it''s used, for example, during shipping from continent to another. Sleep mode is used when a tracker is stored in a warehouse, and it''s triggered by entering or leaving some defined geofence. Power save mode can be enabled with `system.powerSave.sendMs` property in the desired shadow and when enabled the device enters power save mode when the device is not moving. ' type: string enum: - unknown - normal - flight - transport - sleep - powerSave description: 'Contains device-reported sensor data and device configuration settings. `stateVersion` property contains the version of the last known `desired` state seen by the device. ' - type: object properties: computed: description: Values computed by HERE Tracking based on other data available. properties: online: description: Online status of the device. Computed based on the device's reporting rate. If the device has not reported within the time frame of the reporting rate plus five minutes, the device is considered to be offline. If the reporting rate is not specified for the device, a default of 15 minutes is used. type: boolean moving: description: 'Asset is considered moving if the positions of two consecutive trace points differ more than the combined positioning accuracy + 100 meters. ' type: boolean lastMovedTimestamp: description: 'Timestamp referring to the trace point when the asset was last detected moving. Asset is considered moving if the positions of two consecutive trace points differ more than the combined positioning accuracy + 100 meters. ' type: integer outlier: description: 'Indicates that HERE Tracking detected position to be a possible outlier. ' type: object properties: reason: description: Reason why position was considered to be an outlier. type: string correctedPosition: description: HERE Tracking estimate of more correct position. type: object properties: accuracy: description: Uncertainty circle radius in meters (degree of confidence according to the 'confidence' parameter). type: number minimum: 0 lat: description: Latitude in WGS-84 format, decimal representation ranging from -90 to 90. type: number minimum: -90 maximum: 90 lng: description: Longitude in WGS-84 format, decimal representation ranging from -180 to 180. type: number minimum: -180 maximum: 180 timestamp: type: integer description: Milliseconds elapsed since 1 January 1970 00:00:00 UTC. minimum: 2 maximum: 4102448400000 required: - accuracy - lat - lng required: - reason timestamp: description: 'Milliseconds elapsed since 1 January 1970 00:00:00 UTC. The timestamp of the newest telemetry sent by the device. Note that this is not necessarily the timestamp of all the reported values in the reported shadow since the shadow retains values from previous ingestions if the latest telemetry did not conatain them. ' maximum: 4102448400000 minimum: 2 type: integer title: reported example: position: alt: '105' accuracy: '18' lng: '13.38480101' lat: '52.5308544' altaccuracy: '15' '400': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Bad request code: 400 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The request object is in an incorrect format or has values that are invalid or out of range. details: hereErrorCode: 400306 description: 'Bad request The request object is in an incorrect format or has values that are invalid or out of range. If available, further error details are provided in the response body. ' '401': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Unauthorized code: 401 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The provided credentials are not valid. details: hereErrorCode: 401306 description: 'Unauthorized The request did not provide correct authentication details ' '403': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Forbidden code: 403 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The account does not have the correct privileges. details: hereErrorCode: 403306 description: 'Forbidden The account does not have the correct privileges ' '404': description: Not found. Shadow doesn't exist content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id operationId: getShadowsV2ByTrackingIdByState x-operation-id-source: derived /shadows/v2/{trackingId}/{state}/{selector}: parameters: - in: header name: X-Request-Id schema: type: string format: uuid description: 'ID used for correlating requests within HERE Tracking. Used for logging and error reporting. Must be a valid UUIDv4. ' required: false - name: trackingId in: path schema: type: string minLength: 1 maxLength: 50 description: This is a unique ID associated with the device data in HERE Tracking. The `trackingId` gets assigned to a device when the device is claimed by a user. Alternatively, a valid `shipmentId` may be used. required: true - name: appId description: Application identifier. Used together with an external ID to identify a virtual device. schema: type: string minLength: 8 in: query required: false - name: state in: path required: true description: Desired or reported state object of a device to query. schema: type: string enum: - desired - reported - name: selector in: path required: true description: A JSON selector that specifies the property. schema: type: string get: summary: Gets a value of a shadow property description: '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`' security: - UserToken: [] - ClientToken: [] - DeviceToken: [] tags: - Shadows responses: '200': description: 'Successful The content type is defined as "text/plain" or "application/json" depending on the type of the property. ' content: application/json: schema: oneOf: - type: object - type: array example: alt: '105' accuracy: '18' lng: '13.38480101' lat: '52.5308544' altaccuracy: '15' text/plain: schema: type: string example: red '400': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Bad request code: 400 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The request object is in an incorrect format or has values that are invalid or out of range. details: hereErrorCode: 400306 description: 'Bad request The request object is in an incorrect format or has values that are invalid or out of range. If available, further error details are provided in the response body. ' '401': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Unauthorized code: 401 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The provided credentials are not valid. details: hereErrorCode: 401306 description: 'Unauthorized The request did not provide correct authentication details ' '403': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Forbidden code: 403 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The account does not have the correct privileges. details: hereErrorCode: 403306 description: 'Forbidden The account does not have the correct privileges ' '404': description: Not found. Shadow doesn't exist content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code id: type: string format: uuid description: An error ID that allows you to trace the error details message: type: string description: Descriptive text that explains the error details: description: An optional object containing more information about the error required: - error - code - id example: - error: Unauthorized code: 401 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee message: Invalid Authorization, the request lacks valid authentication credentials for the target resource. details: hereErrorCode: 401306 '422': description: The specified property doesn't exist in the shadow for the device. content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code id: type: string format: uuid description: An error ID that allows you to trace the error details message: type: string description: Descriptive text that explains the error details: description: An optional object containing more information about the error required: - error - code - id example: - error: Unauthorized code: 401 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee message: Invalid Authorization, the request lacks valid authentication credentials for the target resource. details: hereErrorCode: 401306 operationId: getShadowsV2ByTrackingIdByStateBySelector x-operation-id-source: derived /shadows/v4: get: summary: Gets all shadows description: Gets all device shadows of a project. security: - UserToken: [] - ClientToken: [] parameters: - in: header name: X-Request-Id schema: type: string format: uuid description: 'ID used for correlating requests within HERE Tracking. Used for logging and error reporting. Must be a valid UUIDv4. ' required: false - name: projectId schema: type: string minLength: 1 maxLength: 50 description: 'Project ID. Any HERE Tracking user must be a member of a Tracking project. The project ID can be implicitly resolved if the user calling the API is a member of a single project. If the user is a member of multiple projects, the `projectId` query parameter needs to be specified explicitly. ' in: query required: false - name: pageToken description: A token from the previously returned response to retrieve the specified page. schema: type: string in: query required: false - name: limit in: query description: The number of items to return per page schema: type: integer minimum: 1 maximum: 1000 default: 100 required: false - name: after in: query required: false description: If provided returns the shadows for which `reported.timestamp` is greater than given `after` parameter. schema: type: string format: date-time - in: query schema: type: string pattern: ^(trackingId|reported.timestamp|desired.timestamp):(asc|desc)$ name: sort description: 'Defines how the items are sorted. The default sort is `sort=trackingId:asc` ' example: reported.timestamp:desc required: false - in: query schema: type: array maxItems: 4 minItems: 4 items: type: number minimum: -180 maximum: 180 description: Latitude and longitude of Northwest and Southeast corners. name: bbox description: 'Limit search to shadows, whose position intersects the given bounding box. The `bbox` array consist of latitude and longitude of Northwest and Southeast corners. ' style: form example: 61.494750,23.775189,61.494611,23.774758 tags: - Shadows responses: '200': description: 'Response body contains an array of shadows along with tracking ID, count indicating the number of returned items, and next page token if available. For virtual devices, a combination of app ID and external ID is provided instead of tracking ID. ' content: application/json: schema: type: object properties: limit: description: Maximum number of items as specified in request type: integer minimum: 1 maximum: 1000 count: description: Number of items returned in the response type: integer minimum: 0 maximum: 1000 nextPageToken: description: Token to fetch the next page (if exists) type: string items: type: array items: type: object properties: shadow: type: object properties: desired: description: 'The desired shadow of the device. ' type: object properties: payload: type: object description: 'A free format JSON object. The maximum size is 1000B. ' system: type: object description: 'Contains device configuration settings. ' properties: powerSave: description: Power save mode parameters. type: object properties: sendMs: description: The rate at which to send sample results in milliseconds in power save mode. A missing or zero value means power save mode is disabled. If present must be bigger than the value of `system.rate.sendMs`. type: number minimum: 0 rate: description: This can be used to specify the rates at which the device performs certain tasks. type: object properties: sampleMs: description: The rate at which to sample signals in milliseconds. Must be smaller than the value of `system.rate.sendMs`. type: number minimum: 0 sendMs: description: The rate at which to send sample results in milliseconds type: number minimum: 0 distanceM: description: Send an update if the device has moved farther than the specified distance in meters type: number minimum: 0 syncGeofences: description: A boolean value that sets efficient geofencing on or off type: boolean detectOutliers: description: A boolean value that sets outlier detection on or off type: boolean disableTracking: type: object description: 'Tracking can be disabled and enabled by defining disableTracking object. In order to disable tracking, one must at least provide the begin time of the disabling period and define either position or sensor properties one wants to disable. One can also disable both position and sensors at the same time. By default tracking is enabled. ' properties: periods: description: 'Define begin and end of the disabling period. All trace points with timestamp that falls between begin and end times will be disabled according to the settings defined in the position and sensors properties. ' type: array minItems: 0 maxItems: 1 title: Array of periods items: type: object properties: begin: description: 'Begin time of the tracking disabling period. Begin must be smaller than end. Begin must be greater or equal to current time. Begin can be set without end. If there exists already end time which is earlier than given new begin time, the existing end time will be deleted. ' type: string format: date-time end: description: 'End time of the tracking disabling period. End must be greater than begin. End must be greater or equal to current time. End can be set without begin if begin is already set. ' type: string format: date-time position: description: Define position methods to be disabled oneOf: - type: string title: all positioning enum: - all description: 'All positioning data the device sends will be removed before further processing. No geofence and location events will be generated ' - type: array minItems: 1 title: specified positioning methods items: type: string enum: - bt - country - gsm - wcdma - tdscdma - lte - cdma - wlan - gps description: 'The items specified in the position array will be removed from the ingestion scan object before further processing. Position may be resolved by the remaining scan properties. Some geofence and location events may be generated. ' - type: string title: re-enable enum: - '' description: 'By setting the position property empty string, all positioning data will be re-enabled during the disabling period. ' sensors: description: Define sensors to be disabled oneOf: - type: string enum: - all title: all sensors description: 'All sensor data the device sends will be removed before further processing. No sensor events will be generated. ' - type: array minItems: 1 title: specified sensors items: type: string enum: - accelerationG - deviceIsAttached - deviceIsStationary - batteryIsCharging - batteryLevel - pressureHpa - relativeHumidity - deviceIsTampered - temperatureC - tiltDegree description: 'The items specified in the sensors array will be removed from the ingestion system.reportedSensorData object before further processing. Sensor events will not be generated for the disabled sensors. ' - type: string title: re-enable enum: - '' description: 'By setting the sensors property empty string, all sensors data will be re-enabled during the disabling period. ' stateVersion: description: 'The version of the state of a device. This should be incremented only by HERE Tracking. ' type: integer minimum: 0 lastModifiedGeofenceTimestamp: description: 'The time of the last update to geofences that device is associated with. This value is zero when device hasn''t yet been associated with any geofence. This is set by HERE Tracking when any geofences associated with the device is modified or removed. Also adding and removing geofence associations update this value. ' type: string format: date-time sensorAlarmConfig: description: 'The device sensors alarm configuration. ' type: object properties: alertTemperatureCMin: type: number description: A lower threshold value for temperature in degrees Celsius. alertTemperatureCMax: type: number description: An upper threshold value for temperature in degrees Celsius. alertRelativeHumidityMin: type: number description: A lower threshold value for relative humidity percentage. alertRelativeHumidityMax: type: number description: An upper threshold value for relative humidity percentage. alertAccelerationGMin: type: number description: A lower threshold value for acceleration in g-forces. alertAccelerationGMax: type: number description: An upper threshold value for acceleration in g-forces. alertTiltDegreeMin: type: number description: A lower threshold value for tilt in degrees. alertTiltDegreeMax: type: number description: An upper threshold value for tilt in degrees. alertPressureHpaMin: type: number description: A lower threshold value for pressure in hectopascals. alertPressureHpaMax: type: number description: An upper threshold value for pressure in hectopascals. alertBatteryLevelPMin: type: number description: A lower threshold value for battery level percentage. alertBatteryLevelPMax: type: number description: An upper threshold value for battery level percentage. isAttachAlertEnabled: type: boolean default: false description: True if attach sensor alert in device is enabled. isTamperAlertEnabled: type: boolean default: false description: True if tamper sensor alert in device is enabled. wlanConnectivityEnabled: description: A boolean value that sets wlan connectivity on or off type: boolean wlanConfigurations: description: An array of objects that holds wlan configurations type: array minItems: 0 maxItems: 10 items: type: object properties: securityMode: description: Selected security mode type: string enum: - none - wpa2psk ssid: description: Name given to a WLAN that is used by the client to access a WLAN network. Please note that the SSID is stored to the device unencrypted. Do not use secure private networks, such as Intranet, for tracker WLAN connectivity. type: string minLength: 1 maxLength: 32 password: description: WLAN password. Please note that the password is stored to the device unencrypted. Do not use secure private networks, such as Intranet, for tracker WLAN connectivity. Password is required if security mode is other then 'none'. type: string minLength: 8 maxLength: 63 ssidIsHidden: description: Flag that informs if SSID is hidden type: boolean additionalProperties: false required: - securityMode - ssid sensorLoggingEnabled: description: Flag that sets sensor logging on or off type: boolean sensorLoggingConfigurations: description: An array of objects that holds sensor logging configurations type: array minItems: 0 maxItems: 5 items: type: object properties: type: description: Type of single sensor logging configuration type: string enum: - acceleration - pressure - temperature - humidity - gnss samplingFrequency: description: Sampling frequrency of single sensor loggin configuration (in milliseconds) type: number minimum: 1 additionalProperties: false required: - type sensorLoggingTag: description: Tag for the logged sensor data. type: string minLength: 1 maxLength: 50 required: - stateVersion - lastModifiedGeofenceTimestamp timestamp: description: 'The time of the last update to the desired shadow. ' type: string format: date-time reported: description: 'The `reported` shadow contains the most recent position, sensor readings and settings that the device has sent. The reported shadow may also contain additional properties generated by HERE Tracking based on the device-ingested telemetry. Such properties are stored in `system.computed` property of the shadow. In case the most recent telemetry did not contain all the possible fields, the last known information will remain in the shadow. This means that one can see, for example, the last reported temperature or tracker firmware information in the reported shadow, even if the device did not send that information in the latest telemetry. ' type: object properties: payload: type: object description: 'A free format JSON object. The maximum size is 1000B. ' position: type: object description: The device location properties: accuracy: description: Uncertainty circle radius in meters (degree of confidence according to the 'confidence' parameter). type: number minimum: 0 alt: description: Altitude in meters (referenced to the WGS-84 ellipsoid) negative or positive. type: number altaccuracy: description: Uncertainty of the altitude estimate in meters (degree of confidence according to the 'confidence' parameter). type: number minimum: 0 confidence: description: Confidence level in percent for the accuracy/uncertainty. If not specified, the default is 68 (this corresponds to a 68% probability that the true position is within the accuracy/uncertainty radius of the position; the higher the number, the greater the confidence level). type: integer minimum: 50 maximum: 95 heading: description: GPS/GNSS heading in degrees, clockwise from true north. You must specify a value for this item when you specify a value for speed. type: integer minimum: 0 maximum: 359 floor: description: The building where the measurements were taken type: object required: - id - name - level properties: level: description: The floor in the building in integer format type: number minimum: -999 maximum: 999 id: description: The building id type: string minimum: 1 maximum: 100 name: description: The building name type: string minimum: 1 maximum: 255 lat: description: Latitude in WGS-84 format, decimal representation ranging from -90 to 90. type: number minimum: -90 maximum: 90 lng: description: Longitude in WGS-84 format, decimal representation ranging from -180 to 180. type: number minimum: -180 maximum: 180 satellitecount: description: Number of GPS/GNSS satellites used for the calculation of the position fix. ('gnss' position type only) type: integer minimum: 1 maximum: 50 speed: description: GPS/GNSS speed of the device (m/s). One must specify a value for this item when one specifies a value for heading. type: integer minimum: 0 type: description: Position type, 'gnss' (satellite based), 'cell' or 'wlan' (network based) type: string wlancount: description: The total number of observed WLAN APs in the scan used for producing the position. ('wlan' position type only) type: integer minimum: 1 maximum: 254 timestamp: type: string format: date-time description: Timestamp of the position required: - lat - lng - accuracy system: allOf: - type: object properties: phoneNumber: type: string pattern: ^\+[1-9]\d{1,14}$ description: 'The phone number of the device''s SIM card in the international E.164 format. All the country codes should be prefixed a with "+" instead of "00". ' example: '+491234567890' imsi: type: string pattern: ^[0-9]{1,15}$ description: 'The IMSI of the device''s SIM card. ' example: '123456789012345' iccid: type: string minLength: 18 maxLength: 22 description: SIM card integrated circuit card identifier (ICCID) client: description: 'Information about the client device. ' type: object properties: manufacturer: description: Manufacturer of the device (hardware) type: string minLength: 2 maxLength: 50 model: description: Model of the device (hardware) type: string minLength: 1 maxLength: 50 firmware: description: Device firmware version information type: string minLength: 1 maxLength: 150 name: description: Name of the client software accessing the HERE API type: string minLength: 3 maxLength: 50 version: description: Version of the client software in format X.Y.Z, where X [0..255] is a major, Y [0..255] is a minor, and Z [0..65535] is a build version number. Increase the version/build number for each release of the client. type: string minLength: 3 maxLength: 60 platform: description: Software platform information of the device, for example operating system name and version. type: string minLength: 3 maxLength: 50 modules: description: Software information of all updateable chips. type: array maxItems: 10 items: description: Software information of an updateable chip. type: object properties: manufacturer: type: string description: Manufacturer name minLength: 2 maxLength: 50 model: type: string description: Model or chip name minLength: 1 maxLength: 50 firmwareVersion: type: string description: Installed firmware version minLength: 3 maxLength: 60 diskquota: description: Available disk quota in kilobytes. type: number minimum: 0 diagnosticscode: description: Device diagnostics code. type: number homenetwork: description: Information about subscriber home network - 3GPP MCC+MNC or 3GPP2 SID+NID. Dual-SIM devices can provide information on both subscriptions. type: array maxItems: 2 items: description: Network information. Either MCC + MNC or SID + NID attribute pair is required. type: object properties: mcc: description: Mobile Country Code type: integer minimum: 200 maximum: 999 mnc: description: Mobile Network Code type: integer minimum: 0 maximum: 999 sid: description: System Id, SID type: integer minimum: 1 maximum: 32767 nid: description: Network Id, NID type: integer minimum: 0 maximum: 65535 hasAttachSensor: type: boolean description: True if a device has a sensor to detect if the device is attached to or detached from an object. hasNoBattery: type: boolean description: False if a device has a battery. hasHumiditySensor: type: boolean description: True if a device has a sensor to measure humidity. hasPressureSensor: type: boolean description: True if a device has a sensor to measure pressure. hasTamperSensor: type: boolean description: True if a device has a sensor to detect if device is disassembled. hasTemperatureSensor: type: boolean description: True if a device has a sensor to measure temperature. hasAccelerometerSensor: type: boolean description: True if a device has a sensor to measure acceleration. accelerometerSensorRange: description: 'Specifies the range of measurable acceleration, representation unit g (9.8 m/s^2). If more than one accelerometer is available, each element in the list will represent individual accelerometer. Each value represents a single "+/-" range. For example, value 2 means that sensor is capable to measure acceleration within the range of [-2 g, +2 g]. ' type: array maxItems: 5 items: type: integer minimum: -1000 maximum: 1000 example: manufacturer: Samsung model: SM-G930F firmware: heroltexx... name: HERE Tracker version: 1.6.1 platform: Android diskquota: 256 diagnosticscode: 0 homenetwork: [] hasAttachSensor: true hasNoBattery: false hasHumiditySensor: true hasPressureSensor: true hasTamperSensor: true hasTemperatureSensor: true hasAccelerometerSensor: true accelerometerSensorRange: - 2 stateVersion: description: 'The version of the state of a device. This should be incremented only by HERE Tracking. ' type: integer minimum: 0 reportedSensorData: description: 'The last known device sensor data reported by the device. ' type: object properties: accelerationG: type: number description: A g-force value of acceleration. minimum: -100 maximum: 100 deviceIsAttached: type: boolean description: True if device is attached to an object. deviceIsStationary: type: boolean description: True if device hasn't detected movement. batteryIsCharging: type: boolean description: True if device battery is charging. batteryLevel: type: integer description: A value of percentage battery level. minimum: 0 maximum: 100 pressureHpa: type: number description: A value of pressure in hectopascal. minimum: 300 maximum: 1500 relativeHumidity: type: number description: A value of relative humidity in percent. minimum: 0 maximum: 100 deviceIsTampered: type: boolean description: True if device is tampered. temperatureC: type: number description: A value of temperature in celcius. minimum: -70 maximum: 100 tiltDegree: type: number description: A value of tilt in degrees. mode: description: 'Tracker mode status of the device. When a tracker is in normal mode, it can send telemetry and, for example, use its GNSS receiver if it has one. A tracker switches into flight mode once it detects that it''s in an airplane, and leaves that mode once the airplane lands. Transport mode has to be triggered by the user, and it''s used, for example, during shipping from continent to another. Sleep mode is used when a tracker is stored in a warehouse, and it''s triggered by entering or leaving some defined geofence. Power save mode can be enabled with `system.powerSave.sendMs` property in the desired shadow and when enabled the device enters power save mode when the device is not moving. ' type: string enum: - unknown - normal - flight - transport - sleep - powerSave description: 'Contains device-reported sensor data and device configuration settings. `stateVersion` property contains the version of the last known `desired` state seen by the device. ' - type: object properties: computed: description: Values computed by HERE Tracking based on other data available. properties: online: description: Online status of the device. Computed based on the device's reporting rate. If the device has not reported within the time frame of the reporting rate plus five minutes, the device is considered to be offline. If the reporting rate is not specified for the device, a default of 15 minutes is used. type: boolean moving: description: 'Asset is considered moving if the positions of two consecutive trace points differ more than the combined positioning accuracy + 100 meters. ' type: boolean lastMovedTimestamp: description: 'Timestamp referring to the trace point when the asset was last detected moving. Asset is considered moving if the positions of two consecutive trace points differ more than the combined positioning accuracy + 100 meters. ' type: string format: date-time outlier: description: 'Indicates that HERE Tracking detected position to be a possible outlier. ' type: object properties: reason: description: Reason why position was considered to be an outlier. type: string correctedPosition: description: HERE Tracking estimate of more correct position. type: object properties: accuracy: description: Uncertainty circle radius in meters (degree of confidence according to the 'confidence' parameter). type: number minimum: 0 lat: description: Latitude in WGS-84 format, decimal representation ranging from -90 to 90. type: number minimum: -90 maximum: 90 lng: description: Longitude in WGS-84 format, decimal representation ranging from -180 to 180. type: number minimum: -180 maximum: 180 timestamp: description: Timestamp for the corrected position type: string format: date-time required: - accuracy - lat - lng required: - reason timestamp: description: 'This describes when the reported measurements were taken. ' type: string format: date-time required: - desired - reported trackingId: type: string minLength: 1 maxLength: 50 description: This is a unique ID associated with the device data in HERE Tracking. The `trackingId` gets assigned to a device when the device is claimed by a user. appId: type: string minLength: 8 description: Virtual device application ID, only present when the device is virtual externalId: type: string minLength: 1 maxLength: 50 description: Virtual device external ID, only present when the device is virtual required: - shadow required: - limit - count - items additionalProperties: false '400': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Bad request code: 400 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The request object is in an incorrect format or has values that are invalid or out of range. details: hereErrorCode: 400306 description: 'Bad request The request object is in an incorrect format or has values that are invalid or out of range. If available, further error details are provided in the response body. ' '401': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Unauthorized code: 401 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The provided credentials are not valid. details: hereErrorCode: 401306 description: 'Unauthorized The request did not provide correct authentication details ' '403': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Forbidden code: 403 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The account does not have the correct privileges. details: hereErrorCode: 403306 description: 'Forbidden The account does not have the correct privileges ' '404': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Not Found code: 404 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The specified resource was not found. details: hereErrorCode: 404306 description: 'Not Found The specified resource was not found ' operationId: getShadowsV4 x-operation-id-source: derived components: securitySchemes: ApiKey: type: apiKey in: query name: apiKey description: 'A key generated specifically to authenticate API requests. For more information on how to get an API key, see the [Identity & Access Management Developer Guide](https://www.here.com/docs/bundle/identity-and-access-management-developer-guide/page/README.html). ' Bearer: type: http scheme: bearer bearerFormat: JWT description: "A token obtained from a separate endpoint using client credentials and an OAuth 1.0a HMAC-SHA256 signed request.\n\nUsers are authenticated using an OAuth 1.0 bearer token obtained using the `/users/v2/login` endpoint.\n\nDevices are authenticated using an OAuth 1.0 bearer token obtained using the `/v2/token` endpoint.\n\n**Make a request using the bearer token for authentication**\n\nMake a request with an `Authorization` header containing the obtained bearer token.\n\nExample:\n\n```\n Authorization: Bearer h1.yxPIksZ0ViLq77f1Nh-9cg.NVgGBZVlCU8G7kjV_...\n```\n\n> **Note:** For the available authentication options, see the [Identity & Access Management Guide](https://www.here.com/docs/bundle/identity-and-access-management-developer-guide/page/README.html).\n" UserToken: type: http scheme: bearer bearerFormat: JWT description: "This token is obtained using user's realm, username and password and then further scoped to a specific project.\n\nFirst obtain access token from [/users/v2/login endpoint](#tag/Users/paths/~1users~1v2~1login/post).\nThen use [/users/v2/tokenExchange endpoint](#tag/Users/paths/~1users~1v2~1tokenExchange/post) to convert\nyour user access token into a project-scoped user access token.\n\nOnce done, make a request with an `Authorization` header containing the scoped access token.\n\nExample:\n\n```\n Authorization: Bearer h1.xikjhDyJsE17VLhPXiu.fm3WsNOunstXH78RvU8_...\n```\n" ClientToken: type: http scheme: bearer bearerFormat: JWT description: "This token is obtained using application's OAuth 2.0 credentials (key + secret) and then scoped to a specific project.\n\nFollow [instructions here](https://www.here.com/docs/bundle/identity-and-access-management-developer-guide/page/topics/plat-token.html)\nto create your application credentials and obtain the token using OLP CLI. With an exception\nthat when getting the token you need to provide also project's HRN value:\n\n```\n olp api token get --scope {PROJECT_HRN}\n```\n\nOnce done, make a request with an `Authorization` header containing the scoped access token.\n\nExample:\n\n```\n Authorization: Bearer h1.PGEVzQmaoW5pyBYUlWu.SQoSCF7qpToEFMHgSlJ_...\n```\n" DeviceToken: type: http scheme: bearer bearerFormat: JWT description: 'This access token is obtained from [/v2/token endpoint](#tag/Ingestion/paths/~1v2~1token/post) using a signed request. > **Note:** Only a small subset of our endpoints support this token type and is only useful for hardware devices. > You probably won''t need this. ' signedRequest: type: http scheme: oauth description: "HERE Tracking requires that you sign your requests for tokens. 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.\n\n> **Note:** You must create a new signature for each token request to HERE Tracking. Signatures can only be used once.\n\n**Create the Signature Base String**\n\nThe first step in creating a signature is to create the signature base string. This string contains the parameters to use when generating the signature.\n\n*1. To begin, make sure you have the information listed in the following table.*\n\n| Parameter | Description |\n| ------------------------ | -----------------------------------------|\n| oauth\\_consumer\\_key | The device ID for which you want to generate a token. |\n| oauth\\_signature\\_method | Always use \"HMAC-SHA256\". |\n| oauth\\_timestamp | The number of seconds since the Unix epoch at the point the request is generated. This must be within 10 seconds of the timestamp returned by the `/v2/timestamp` endpoint. |\n| oauth\\_nonce | A unique string for this signature. The string cannot have been used in a previous signature. Each token generation request to HERE Tracking must have a unique signature, and the value in this parameter is what is used to ensure the signature is unique. |\n| oauth\\_version | Always use \"1.0\". |\n\n*2. Combine these values into a single string by following these steps:*\n\n 1. URL encode every key and value.\n 2. Sort the list of key-value pairs alphabetically by key.\n 3. Concatenate each key/value pair, separating each with an ampersand character (\"&\").\n\nThe result is a parameter string that looks like this (line breaks are added for legibility):\n\n ```\n oauth_consumer_key=47164fb0-b7b3-49e8-891b-650270b82cf2\n &oauth_nonce=LIIpk4\n &oauth_signature_method=HMAC-SHA256\n &oauth_timestamp=1513634609\n &oauth_version=1.0\n ```\n\n*3. Combine the HTTP method, base URL, and parameter string into a single string called the \"base string\". This will be the string from which the signature is generated. The base string is in this format:*\n\n ```\n POST&https://tracking.api.here.com/v2/token&\n ```\n\n The base string consists of:\n\n 1. The HTTP method in caps (POST) followed by an ampersand (\"&\")\n 2. The URL of the HERE Tracking token endpoint followed by an ampersand (\"&\")\n 3. The URL-encoded parameter string.\n\n For example (line breaks are added for legibility):\n\n ```\n POST\n &https%3A%2F%2Ftracking.api.here.com%2Fv2%2Ftoken\n &oauth_consumer_key%3D47164fb0-b7b3-49e8-891b-650270b82cf2%26\n oauth_nonce%3DLIIpk4%26oauth_signature_method%3DHMAC-SHA256%26\n oauth_timestamp%3D1513634609%26oauth_version%3D1.0\n ```\n\n > **Note:** The URL-encoded base string should contain exactly two ampersands (\"&\").\n\n**Create the signature**\n\nThe signing key used to sign the base string is the `deviceSecret` followed by an ampersand (\"&\").\n\nCreate the signature by passing the signature base string and the signing key to the `HMAC-SHA256` hashing algorithm and converting the result to a `base64` string. Then, use the signature to request a token.\n\n**Request the token**\n\nMake a `POST` request to this endpoint with an `Authorization` header constructed from the above parameters and the generated signature.\n\nExample:\n\n```\n Authorization: OAuth oauth_consumer_key=\"47164fb0-b7b3-49e8-891b-650270b82cf2\",\n oauth_signature_method=\"HMAC-SHA256\",\n oauth_timestamp=\"1513634609\",\n oauth_nonce=\"LIIpk4\",\n oauth_version=\"1.0\",\n oauth_signature=\"pQ9EJX14L736B%2Br7uZl4yQlO6Xw%3D\"\n```\n" externalDocs: description: The Developer guide and Release notes are available here. url: https://www.here.com/docs/bundle/tracking-api-developer-guide