# Obtain the location of Devices (Asynchronous) ### `POST /devicelocations` Finds the current or cached location of up to 10,000 IoT devices. This request returns a synchronous transaction ID and the location information for each device is returned asynchronously as a `DeviceLocation` callback message. Devices can only be located by the account that owns them and only the account that owns the devices being queried is allowed to request their location. This method can only be used for IoT and Fixed Wireless Access (FWA) devices. **End-user consent required to locate devices** For devices, the device owner must give consent for the device location information to be determined and reported. When a location request is sent for a device, ThingSpace checks to see if there is a current consent for the account to access the specified device’s location. If there isn’t a consent on file, or consent is denied, ThingSpace will not proceed further to compute the location information of the device and a callback will be sent with an error. If the account owner gives consent, or if there is already a current consent, the location information will be returned in a `DeviceLocation` callback message. **Current or Cached Location** A device’s current location can be requested or the previous location requested from the cache. Users can specify `maxLocAge` to specify the age of the location that can be accepted for cached location (this is used when `cacheMode` is set to **cached** or **current**). Each request for a device’s current location overwrites the stored location in the cache. There is no charge for retrieving a device’s cached location. **Location Accuracy** The requested accuracy may or may not be met due to device capability and other network restrictions. ## Header Parameters The request header must set the content-type to JSON, contain a current ThingSpace authorization token and a current VZ-M2M session token. For more details on how to get these tokens, visit [Getting Started](https://thingspace.verizon.com/documentation/api-documentation.html#/http/session-management/guides/getting-started). | Parameter Name | Data Type | Description | | ------------------------------ | --------- | ---------------------------------------------------------------- | | **Authorization** *(required)* | string | HTTP Authorization bearer token: `Authorization: Bearer {token}` | | **VZ-M2M-Token** *(required)* | string | A valid session token: `VZ-M2M-Token: {M2Mtoken}` | | **Content-Type** *(required)* | string | Must be application/json `Content-Type: application/json` | ## HTTP Request [POST https://thingspace.verizon.com/api/loc/v1/devicelocations](/docs/premium-apis/device-location/api-endpoints/devices-locations/listdeviceslocationsasynchronous) ## Request Parameters |Property Name|Data Type|Description| |-----|-----|-----| | **accountName** *(required)* | string | The numeric name of a billing account. Any leading zeros must be included. | | **accuracyMode** *(optional)* | string | An integer (as a string) representing the requested accuracy of the returned location: **0**: coarse accuracy, **1**: precise accuracy, **2**: reserved for future enhancements. | | **cacheMode** *(optional)* | string | An integer (as a string) indicating whether current or cached location information should be returned. Valid values are: **0** - Cached. (Default) Information from the last successful device location check is returned or an error message is returned if there is no cached information for a device. There is no billing charge for requesting cached location information (Ignore `maxLocAge` and just return cached location), **1** - Cached or current. ThingSpace first looks for cached information for the device and returns that if it exists. If there is no cached information, it finds the current location of the device and returns that information and then stores the current location in the cache (A location within `maxLocAge`, if available, is returned. If that is not available, then a current location is triggered), **2** - Current. Returns the current location of the device and stores that location information in the cache (Ignore `maxLocAge` and just return current location). | | **maxLocAge** *(optional)* | string | An integer (as a string) indicating maximum tolerable age in seconds of position estimates used for cached position fixes if another position was computed due to another request. The range is from **0** to **3600** seconds. The default is **120** seconds, if not specified. | | **deviceList** *(required)* | array | Each object in the array identifies a device to locate and will have a `kind` and `id`. **Note:** `deviceList` can contain a maximum of 10,000 devices | | **id** *(required)* | string | A device identifier value. | | **kind** *(required)* | string | The type of the identifier, which is an International Mobile Equipment ID (**IMEI**). | | **mdn** *(required)* | string | The Mobile Directory Number (MDN) of the device | ## Request Body The body contains the account name and list of devices that are to be located, plus other options. Example Request Body: ```json { "accountName": "0000123456-00001", "accuracyMode": "1", "cacheMode": "2", "maxLocAge": 120, "deviceList": [ { "id": "900000000000009", "kind": "imei", "mdn": "10-digit phone number" } ] } ``` ## Success Response **Status 200** A successful response returns a unique transaction ID that can be used to associate callback messages with the original request. Example Response: ```json { "transactionID": "2a076c21-eeee-ffff-gggg-b0a50c372528", "status": "QUEUED" } ``` ## Success Parameters |Parameter Name|Data Type|Description| |-----|-----|-----| | **transactionID** | string | A unique string (UUID) that associates the request with the device location information that is sent in an asynchronous callback message. ThingSpace will send a separate callback message for each device that was in the request. All of the callback messages will have the same `transactionID`. | | **status** | string | The status of request. This will display **QUEUED** for successful requests. | ## Callback Response These endpoints send responses asynchronously. In order to read the results a callback is required. To learn more about callbacks, please visit [About Callback Services](https://thingspace.verizon.com/documentation/api-documentation.html#/http/connectivity-management/guides/working-with-verizon-wireless/about-callback-services). Example callback, **SUCCESS**: ```json { "accountName":"0000123456-00001", "deviceList":[ { "id":"900000000000009", "kind":"IMEI", "mdn":"10-digit phone number", "positionData":{ "cachedReason":"1", "locationType":"0", "radius":"487.0000000", "time":"20240730042910", "x":"32.8981133", "y":"-117.1997910" } } ], "reportType":"LOCATION_REPORT", "status":"SUCCESS", "transactionID":"2a076c21-eeee-ffff-gggg-b0a50c372528" } ``` Example callback, **FAILED**: ```json { "accountName": "0000123456-00001", "deviceList": [ { "error": { "info": "Specified device ID was excluded from using the service", "time": "202407030050827", "type": "TS CONSENT CHECK FAILED" }, "id": "900000000000009", "kind": "IMEI", "mdn": "10-digit phone number" } ], "reportType": "LOCATION_REPORT", "status":"FAILED", "transactionID": "2a076c21-eeee-ffff-gggg-b0a50c372528" } ``` ## Callback Parameters Each callback contains an array that has the position data or an error for a single device request. |Parameter Name|Data Type|Description| |-----|-----|-----| | **accountName** *(required)* | string | The numeric name of a billing account. | | **id** *(required)* | string | A device identifier value. | | **kind** *(required)* | string | The type of the identifier. | | **mdn** *(required)* | string | The Mobile Directory Number (phone number) of the device. | | **positionData** *(optional)* | object | The details of the device's position. This will be empty if position data is not available for the device. | | **x** *(required)* | string | The X coordinate (latitude) of the device in decimal degree format. | | **y** *(required)* | string | The Y coordinate (longitude) of the device in decimal degree format. | | **radius** *(required)* | string | The radius of the location precision in meters. A smaller radius indicates a more precise location. | | **qos** *(optional)* | boolean | Indicates if Quality of Service (QoS) is met (for Coarse Location only). | | **time** *(required)* | string | The time that the location was reported. If the request was for “cached or current” information (`"cacheMode": "1"`), the time value can be used to determine if the location is cached or current data. | | **error** *(optional)* | object | Error type and details. This will be empty if there was no error. This will be empty if there was no error. If the location was not retrieved because it was offline, an error appears. However,ThingSpace will attempt to retrieve a location as soon as it is reachable. | | **type** *(required)* | string | The error type. See [error codes](https://thingspace.verizon.com/documentation/api-documentation.html#/http/device-location/error-codes) for a list of possible errors. | | **info** *(required)* | string | Additional error information. | | **time** *(required)* | string | The time that the error was reported. | | **locationType** *(optional)* | string | An integer (as a string) representing whether the cached or current location returned. Valid values are: **0** - cached and **1** - current. | | **cachedReason** *(optional)* | string | An integer (as a string) representing why the cached location returned. Valid values are: **0** - user requested cache and **1** - location computed within `maxLocAge` available. | | **reportType** *(required)* | string | A string representing the report the callback is reporting. This can be: **CONSENT_RESPONSE**, **LOCATION_REPORT** or **STOP_PERIODIC_LOCATION_RESPONSE**. | | **status** *(required)* | string | This will show **SUCCESS** when data is retrieved or **FAILED** if there is an error. | | **transactionID** *(optional)* | string | A unique string (UUID) that associates the request with the location report information that is sent in an asynchronous callback message. ThingSpace will send a separate callback message for each device that was in the request. All of the callback messages for the same device will have the same `transactionID`. **Note:** A `transactionID` is not included for device initiated location responses, as these are generated without any transaction initiated from ThingSpace. | ## Failure Responses All error messages are returned in this format: ```json { "errorCode": "The 3-digit HTML error code", "errorMessage": "string" } ``` Error codes and messages are listed on the [Error Codes page](https://thingspace.verizon.com/documentation/api-documentation.html#/http/device-location/error-codes), along with explanations and suggestions for corrective actions.