Get Device Location - Asynchronous
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.
| 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
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:
{
"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:
{
"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. Example callback, SUCCESS:
{
"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:
{
"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 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:
{
"errorCode": "The 3-digit HTML error code",
"errorMessage": "string"
}Error codes and messages are listed on the Error Codes page, along with explanations and suggestions for corrective actions.