--- title: "Gets a device shadow" method: GET path: "/shadows/v2/{trackingId}" tags: ["Shadows"] --- # Gets a device shadow `GET /shadows/v2/{trackingId}` 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. ## Path parameters - `trackingId` string, required — This is a unique ID associated with the device data in HERE Tracking. For physical devices the `trackingId` gets assigned to a device when the device is claimed by a user, and for virtual devices it is an external device ID along with the device project `appId`. Alternatively, a valid `shipmentId` may be used. ## Response `200` Successful The device shadow was successfully retrieved. - object — The data that Shadows persists for each device. - `desired` object — The desired shadow of the device. - `payload` object — A free format JSON object. The maximum size is 1000B. - `system` object — Contains device configuration settings. - `detectOutliers` boolean — A boolean value that sets outlier detection on or off - `disableTracking` object — 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. - `periods` object[] — 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. - `begin` integer — 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. - `end` integer — 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. - `position` union — Define position methods to be disabled - 'all' — All positioning data the device sends will be removed before further processing. No geofence and location events will be generated - string[] - '' — By setting the position property empty string, all positioning data will be re-enabled during the disabling period. - `sensors` union — Define sensors to be disabled - 'all' — All sensor data the device sends will be removed before further processing. No sensor events will be generated. - string[] - '' — By setting the sensors property empty string, all sensors data will be re-enabled during the disabling period. - `lastModifiedGeofenceTimestamp` integer, required — 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. - `rate` object — This can be used to specify the rates at which the device performs certain tasks. - `distanceM` number — Send an update if the device has moved farther than the specified distance in meters - `sampleMs` number — The rate at which to sample signals in milliseconds - `sendMs` number — The rate at which to send sample results in milliseconds - `sensorAlarmConfig` object — The device sensors alarm configuration. - `alertAccelerationGMax` number — An upper threshold value for acceleration in g-forces. - `alertAccelerationGMin` number — A lower threshold value for acceleration in g-forces. - `alertBatteryLevelPMax` number — An upper threshold value for battery level percentage. - `alertBatteryLevelPMin` number — A lower threshold value for battery level percentage. - `alertPressureHpaMax` number — An upper threshold value for pressure in hectopascals. - `alertPressureHpaMin` number — A lower threshold value for pressure in hectopascals. - `alertRelativeHumidityMax` number — An upper threshold value for relative humidity percentage. - `alertRelativeHumidityMin` number — A lower threshold value for relative humidity percentage. - `alertTemperatureCMax` number — An upper threshold value for temperature in degrees Celsius. - `alertTemperatureCMin` number — A lower threshold value for temperature in degrees Celsius. - `alertTiltDegreeMax` number — An upper threshold value for tilt in degrees. - `alertTiltDegreeMin` number — A lower threshold value for tilt in degrees. - `isAttachAlertEnabled` boolean — True if attach sensor alert in device is enabled. - `isTamperAlertEnabled` boolean — True if tamper sensor alert in device is enabled. - `sensorLoggingConfigurations` object[] — An array of objects that holds sensor logging configurations - `samplingFrequency` number — Sampling frequrency of single sensor loggin configuration (in milliseconds) - `type` 'acceleration' | 'pressure' | 'temperature' | 'humidity' | 'gnss', required — Type of single sensor logging configuration - `sensorLoggingEnabled` boolean — Flag that sets sensor logging on or off - `stateVersion` integer, required — The version of the state of a device. This should be incremented only by HERE Tracking. - `syncGeofences` boolean — A boolean value that sets efficient geofencing on or off - `wlanConfigurations` object[] — An array of objects that holds wlan configurations - `password` string — 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'. - `securityMode` 'none' | 'wpa2psk', required — Selected security mode - `ssid` string, required — 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. - `ssidIsHidden` boolean — Flag that informs if SSID is hidden - `wlanConnectivityEnabled` boolean — A boolean value that sets wlan connectivity on or off - `timestamp` integer — Milliseconds elapsed since 1 January 1970 00:00:00 UTC. The time of the last update to the desired shadow. - `reported` object — 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. - `payload` object — A free format JSON object. The maximum size is 1000B. - `position` object — The device location - `accuracy` number, required — Uncertainty circle radius in meters (degree of confidence according to the 'confidence' parameter). - `alt` number — Altitude in meters (referenced to the WGS-84 ellipsoid) negative or positive. - `altaccuracy` number — Uncertainty of the altitude estimate in meters (degree of confidence according to the 'confidence' parameter). - `confidence` integer — 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). - `floor` object — The building where the measurements were taken - `id` string, required — The building id - `level` number, required — The floor in the building in integer format - `name` string, required — The building name - `heading` integer — GPS/GNSS heading in degrees, clockwise from true north. You must specify a value for this item when you specify a value for speed. - `lat` number, required — Latitude in WGS-84 format, decimal representation ranging from -90 to 90. - `lng` number, required — Longitude in WGS-84 format, decimal representation ranging from -180 to 180. - `satellitecount` integer — Number of GPS/GNSS satellites used for the calculation of the position fix. ('gnss' position type only) - `speed` integer — GPS/GNSS speed of the device (m/s). One must specify a value for this item when one specifies a value for heading. - `timestamp` integer — Timestamp of the position - `type` string — Position type, 'gnss' (satellite based), 'cell' or 'wlan' (network based) - `wlancount` integer — The total number of observed WLAN APs in the scan used for producing the position. ('wlan' position type only) - `system` object — Contains device-reported sensor data and device configuration settings. `stateVersion` property contains the version of the last known `desired` state seen by the device. - `client` object — Information about the client device. - `accelerometerSensorRange` integer[] — 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]. - `diagnosticscode` number — Device diagnostics code. - `diskquota` number — Available disk quota in kilobytes. - `firmware` string — Device firmware version information - `hasAccelerometerSensor` boolean — True if a device has a sensor to measure acceleration. - `hasAttachSensor` boolean — True if a device has a sensor to detect if the device is attached to or detached from an object. - `hasHumiditySensor` boolean — True if a device has a sensor to measure humidity. - `hasNoBattery` boolean — False if a device has a battery. - `hasPressureSensor` boolean — True if a device has a sensor to measure pressure. - `hasTamperSensor` boolean — True if a device has a sensor to detect if device is disassembled. - `hasTemperatureSensor` boolean — True if a device has a sensor to measure temperature. - `homenetwork` object[] — Information about subscriber home network - 3GPP MCC+MNC or 3GPP2 SID+NID. Dual-SIM devices can provide information on both subscriptions. - `mcc` integer — Mobile Country Code - `mnc` integer — Mobile Network Code - `nid` integer — Network Id, NID - `sid` integer — System Id, SID - `manufacturer` string — Manufacturer of the device (hardware) - `model` string — Model of the device (hardware) - `modules` object[] — Software information of all updateable chips. - `firmwareVersion` string — Installed firmware version - `manufacturer` string — Manufacturer name - `model` string — Model or chip name - `name` string — Name of the client software accessing the HERE API - `platform` string — Software platform information of the device, for example operating system name and version. - `version` string — 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. - `computed` object — Values computed by HERE Tracking based on other data available. - `lastMovedTimestamp` integer — 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. - `moving` boolean — Asset is considered moving if the positions of two consecutive trace points differ more than the combined positioning accuracy + 100 meters. - `online` boolean — 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. - `outlier` object — Indicates that HERE Tracking detected position to be a possible outlier. - `correctedPosition` object — HERE Tracking estimate of more correct position. - `accuracy` number, required — Uncertainty circle radius in meters (degree of confidence according to the 'confidence' parameter). - `lat` number, required — Latitude in WGS-84 format, decimal representation ranging from -90 to 90. - `lng` number, required — Longitude in WGS-84 format, decimal representation ranging from -180 to 180. - `timestamp` integer — Milliseconds elapsed since 1 January 1970 00:00:00 UTC. - `reason` string, required — Reason why position was considered to be an outlier. - `iccid` string — SIM card integrated circuit card identifier (ICCID) - `imsi` string — The IMSI of the device's SIM card. - `mode` 'unknown' | 'normal' | 'flight' | 'transport' | 'sleep' — Tracker mode status of the device. When a tracker is in a 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 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. - `phoneNumber` string — 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". - `reportedSensorData` object — The last known device sensor data reported by the device. - `accelerationG` number — A g-force value of acceleration. - `batteryIsCharging` boolean — True if device battery is charging. - `batteryLevel` integer — A value of percentage battery level. - `deviceIsAttached` boolean — True if device is attached to an object. - `deviceIsStationary` boolean — True if device hasn't detected movement. - `deviceIsTampered` boolean — True if device is tampered. - `pressureHpa` number — A value of pressure in hectopascal. - `relativeHumidity` number — A value of relative humidity in percent. - `temperatureC` number — A value of temperature in celcius. - `tiltDegree` number — A value of tilt in degrees. - `stateVersion` integer — The version of the state of a device. This should be incremented only by HERE Tracking. - `timestamp` integer — 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. ## Other responses - `400` — 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` — Unauthorized The request did not provide correct authentication details - `403` — Forbidden The account does not have the correct privileges - `404` — Not found. No shadow exists for the requested trackingId. --- [API](https://skmtc.net/here/apis/tracking.md) · [All operations](https://skmtc.net/here/apis/tracking/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/here/tracking/versions/efa162f7023c/schema)