--- title: "Ingests data for multiple devices" method: POST path: "/v3/batch" tags: ["Ingestion"] --- # Ingests data for multiple devices `POST /v3/batch` Device owner use this endpoint to ingest data to HERE Tracking on behalf of multiple devices. A single request can contain data for multiple devices. The devices can be either real or virtual. A real device is identified by a `trackingId` assigned to it when the device was claimed. A virtual device is identified by an external device ID and the owner's project `appId`. Prior to making the request, the device owner should first authenticate himself with HERE Tracking and obtain a user access token. The user access token will then be used in this API call. For more information on the device position resolution, and the device shadow and trace updates, see the `/v3` endpoint description. ## Headers - `X-Request-Id` string, uuid - `authorization` string, required ## Request body - object - `appId` string — The user's project appId. Used together with an external ID to identify the virtual devices. - `data` object[], required - `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) - `scan` object — Radio measurements used for positioning or radio map contribution. - `bt` object[] — Bluetooth access points - `eddystoneId` string — Full Identifier as Base64 string. A combination of 10-byte Namespace component and a 6-byte Instance component - `iBeaconId` string — Full Identifier as Base64 string. A combination of 16-byte UUID + 2-byte major + 2-byte minor - `mac` string — The MAC address of the Bluetooth access point. MAC-48 address with colon (:) or hyphen (-) separators, upper or lower case hex digits. For privacy reasons positioning based on a single Bluetooth AP is not possible. There must be at least one other matching WLAN or Bluetooth access point. Either MAC, EddystoneId, or iBeaconId is required. - `rss` integer, required — Received signal strength (dBm) at the terminal - `timestamp` string, date-time — Time of the measurement (UTC) - `cdma` object[] — CDMA cells - `baselat` number — Base station latitude (Optional) - `baselng` number — Base station longitude (Optional) - `bsid` integer, required — Base Station ID, BID - `channel` integer — CDMA channel frequency (Optional, you must specify a value for this item when you specify a value for pnoffset) - `nid` integer, required — Network Id, NID - `nmr` object[] — CDMA Network measurements (Optional) - `bsid` integer — Base Station ID (Optional) - `channel` integer, required — CDMA channel frequency - `frequency` integer — Deprecated. Use 'channel' instead. - `pilotpower` integer — Pilot Power (dBm) (Optional). If Pilot Power is not available directly, it needs to be calculated from Total Power in the band and Pilot Strength with respect to the Total Power. Pilot power less than -142dBm should be mapped to -142. Pilot power greater than -49dBm should be mapped to -49. - `pnoffset` integer, required — Pseudonoise offset - `pilotpower` integer — Pilot Power (dBm) (Optional). If Pilot Power is not available directly, it needs to be calculated from Total Power in the band and Pilot Strength with respect to the Total Power. Pilot power less than -142dBm should be mapped to -142. Pilot power greater than -49dBm should be mapped to -49. - `pnoffset` integer — Pseudonoise offset (Optional, you must specify a value for this item when you specify a value for channel) - `rz` integer — Registration zone (Optional) - `sid` integer, required — System Id, SID - `timestamp` string, date-time — Time of the cell measurement (UTC) (Optional) - `country` object — Indicates in which country the WLAN APs are located (in case cell data is not present in radio_observations) - `mcc` integer, required — Mobile Country Code - `gps` object — Optionally supply this to improve HERE Tracking's positioning service by contributing the scan data along with a GPS position. - `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). - `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 — Milliseconds elapsed since 1 January 1970 00:00:00 UTC. - `gsm` object[] — GSM cells (GERAN) - `bcch` integer — Broadcast Control Channel (Synonymous to ARFCN = Absolute Radio Frequency Channel) (Optional, you must specify a value for this item when you specify a value for bsic). - `bsic` integer — Base Station Identity Code (for instance, color code) (Optional, you must specify a value for this item when you specify a value for bcch). - `cid` integer, required — Cell Identifier, 16 bits. Mcc+mnc+lac+cid uniquely identifies the GSM cell. - `lac` integer, required — Location Area Code - `mcc` integer, required — Mobile Country Code - `mnc` integer, required — Mobile Network Code - `nmr` object[] — Network measurements (Optional) - `bcch` integer, required — Broadcast Control Channel (Synonymous to ARFCN = Absolute Radio Frequency Channel) - `bsic` integer, required — Base Station Identity Code (for instance, color code) - `cid` integer — Cell Identifier (Optional) - `lac` integer — Location Area Code (Optional) - `rxlevel` integer — Received Signal power (dBm) (Optional). Power less than -110dBm should be mapped to -110. Power greater than -25dBm should be mapped to -25. - `rxlevel` integer — Received Signal power (dBm) (Optional). Power less than -110dBm should be mapped to -110. Power greater than -25dBm should be mapped to -25. - `ta` integer — Timing advance (Optional). Expressed in the units of GSM bits equaling to 48/13 μs ~ 1107 meters. - `timestamp` string, date-time — Time of the cell measurement (UTC) (Optional) - `lte` object[] — LTE cells (E-UTRA, 4G) - `cid` integer, required — E-UTRA Cell Identifier, 28 bits (20 bits eNodeB and 8 bits Cell id). Mcc+mnc+cid uniquely identifies the LTE cell, tac is optional. - `earfcn` integer — Evolved Absolute Radio Frequency Channel (Optional, you must specify a value for this item when you specify a value for pci) - `mcc` integer, required — Mobile Country Code - `mnc` integer, required — Mobile Network Code - `nmr` object[] — Network measurements (Optional) - `cid` integer — E-UTRA Cell Identifier (Optional) - `earfcn` integer, required — Evolved Absolute Radio Frequency Channel - `pci` integer, required — Physical Cell Identity - `rsrp` integer — Reference Signal Received Power = RSRP (dBm) (Optional, you must specify a value for this item when you specify a value for rsrq). Power less than -140dBm should be mapped to -140. Power greater than -44dBm should be mapped to -44. - `rsrq` number — Reference Signal Received Quality = RSRQ (dB) (Optional). Values less than -19.5dB should be mapped to -19.5, and values greater than -3dB should be mapped to -3dB. - `pci` integer — Physical Cell Identity (Optional, you must specify a value for this item when you specify a value for earfcn) - `rsrp` integer — Reference Signal Received Power = RSRP (dBm) (Optional, you must specify a value for this item when you specify a value for rsrq). Power less than -140dBm should be mapped to -140. Power greater than -44dBm should be mapped to -44. - `rsrq` number — Reference Signal Received Quality = RSRQ (dB) (Optional). Values less than -19.5dB should be mapped to -19.5, and values greater than -3dB should be mapped to -3dB. - `ta` integer — Timing Advance (Optional). Expressed in the units of 16*Ts (16 Basic time units) = 16/(15000*2048) seconds ~ 156meters. For reference see TS 36.213 and 36.211. - `tac` integer — Tracking Area Code (Optional) - `timestamp` string, date-time — Time of the cell measurement (UTC) (Optional) - `tdscdma` object[] — TD-SCDMA cell (UTRA-TDD, 3G UMTS TDD) - `cellparams` integer — Cell Parameters ID (CDMA Spreading Code ID) (Optional, you must specify a value for this item when you specify a value for uarfcn). - `cid` integer, required — UTRAN Cell Identifier, 28 bits (12 bits RNC and 16 bits Cell id). Mcc+mnc+cid uniquely identifies the TDSCDMA cell, lac is optional. - `lac` integer — Location Area Code (Optional) - `mcc` integer, required — Mobile Country Code - `mnc` integer, required — Mobile Network Code - `nmr` object[] — Network measurements (Optional). Maximum of 8 uarfcndl times maximum of 32 psc. - `cellparams` integer, required — Cell Parameters ID (CDMA Spreading Code ID) - `cid` integer — Cell Identifier (uc-id) (Optional) - `pathloss` integer — UTRAN path loss (dB) (Optional, you must specify a value for this item when you specify a value for rscp). - `rscp` integer — Received Signal Code Power = RSCP (dBm) (Optional, you must specify a value for this item when you specify a value for pathloss). Power less than -120dBm should be mapped to -120. Power greater than -25dBm should be mapped to -25. - `uarfcn` integer, required — Carrier frequency of a UTRA-TDD Serving Cell - `pathloss` integer — UTRAN path loss (dB) (Optional, you must specify a value for this item when you specify a value for rscp). - `rscp` integer — Received Signal Code Power = RSCP (dBm) (Optional, you must specify a value for this item when you specify a value for pathloss). Power less than -120dBm should be mapped to -120. Power greater than -25dBm should be mapped to -25. - `ta` integer — Timing advance (Optional). Round-Trip distance presented in the units of 4*c/7.68e6 ~156 meters. That is, the scaling factor is 4 times the chip length at chip rate of 7.68 Mchips/s. Note that at chip rates 1.28 Mchips/s and 3.84 Mchips/s you need to scale according to chip length of 7.68 Mchips/s, that is, multiply by 6 or 2 if needed. - `timestamp` string, date-time — Time of the cell measurement (UTC) (Optional) - `uarfcn` integer — Carrier frequency of a UTRA-TDD Serving Cell (Optional, you must specify a value for this item when you specify a value for cellparams). - `wcdma` object[] — WCDMA cells (UTRA-FDD, 3G UMTS) - `cid` integer, required — UTRAN Cell Identifier, 28 bits (12 bits RNC and 16 bits Cell id). Mcc+mnc+cid uniquely identifies the WCDMA cell, lac is optional. - `lac` integer — Location Area Code (Optional) - `mcc` integer, required — Mobile Country Code - `mnc` integer, required — Mobile Network Code - `nmr` object[] — Network measurements (Optional). Maximum of 8 uarfcndl times maximum of 32 psc. - `cid` integer — UTRAN Cell Identifier (uc-id) (Optional) - `pathloss` integer — UTRAN path loss (dB) (Optional). - `psc` integer, required — Primary Scrambling Code (Primary CPICH, Primary Control Pilot Channel) - `rscp` integer — Received Signal Code Power = RSCP (dBm) (Optional). Power less than -120dBm should be mapped to -120. Power greater than -25dBm should be mapped to -25. - `uarfcndl` integer, required — Downlink frequency of a UTRA-FDD Serving Cell - `pathloss` integer — UTRAN path loss (dB) (Optional). - `psc` integer — Primary Scrambling Code (Primary CPICH, Primary Control Pilot Channel) (Optional, you must specify a value for this item when you specify a value for uarfcndl). - `rscp` integer — Received Signal Code Power = RSCP (dBm) (Optional). Power less than -120dBm should be mapped to -120. Power greater than -25dBm should be mapped to -25. - `timestamp` string, date-time — Time of the cell measurement (UTC) (Optional) - `uarfcndl` integer — Downlink frequency of a UTRA-FDD Serving Cell (Optional, you must specify a value for this item when you specify a value for psc). - `wlan` object[] — WLAN access points - `band` 2.4 | 3.65 | 5 — Frequency range (GHz). Allowed values are 2.4, 3.65, and 5. (Possible future values include 4.9, 5.9, 60, and 900.) - `mac` string, required — The MAC address of the WLAN access point. MAC-48 address with colon (:) or hyphen (-) separators, upper or lower case hex digits. Note that if the SSID contains postfix '_nomap', the AP should not be used for positioning. For privacy reasons positioning based on a single WLAN AP is not possible; there has to be at least one other matching wlan or cell. - `powrx` integer — Received signal level (dBm) at the terminal (Optional) - `timestamp` string, date-time — Time of the wlan measurement (UTC) (Optional) - `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. - `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, required — Milliseconds elapsed since 1 January 1970 00:00:00 UTC. Specifies the time the device telemetry measurements were taken. - `id` string — Tracking ID or application specific external ID. ## Response `204` Successful (no content) The device data was ingested successfully. ## 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 The specified resource was not found - `413` — Payload Too Large The request size exceeds the maximum size limit for payloads. - `429` — Rate limited. When a device exceeds the number of requests allowed in plan configured for the `appId`, it will receive "Too Many Requests" 429 error code along with following headers: | header | description | | ------------------------ | ----------------------------------------- | | X-RateLimit-Remaining | The remaining number of requests | | X-RateLimit-Limit | The allowed number of requests for the `appId` plan | | Retry-After | The number of seconds the device needs to wait before retrying the data ingestion | --- [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)