POST /devicelocationsFinds the current or cached location of up to 10,000 devices. This request returns a synchronous transaction ID and the location information for each device is returned asynchronously as a DeviceLocation callback message.
Obtain the location of Devices (asynchronous) POST /devicelocations
Cancel Asynchronous Device Location Request
Obtain Device Locations (synchronous)
Create a Device Location Report
Register a Callback Listener
Obtain location service subscription status
About Location Information
About Callback Services
This method can only be used to locate IoT and Fixed Wireless Access (FWA) devices.
Only the account that owns the devices being queried is allowed to request their location.
For devices, the device owner must give their 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 your 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 callback message
You can request a device’s current location, or request the previous location from the cache. Customer 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.
The requested accuracy may or may not be met due to device capability and other network restrictions. The response will have a qos (Quality Of Service) parameter to indicate if the requested accuracy was met (for “Coarse” only). The User can ask for “Coarse” or “Precise” accuracy using the accuracyMode.
The device needs to be powered on and connected to the network to retrieve the location. ThingSpace will store the last known (successful) location within the Extended Diagnostics API. If the device is offline or otherwise unreachable, the request status will likely fail and show an error. However, as soon as the device powers on and connects to the network, ThingSpace will retry to retrieve the location. To be notified when the device is reachable, use the Reachability API. The Extended Diagnostic API can be called subsequently to retrieve the updated location ThingSpace retrieved from the network.
POST https://thingspace.verizon.com/api/loc/v1/devicelocationsNone.
The request header must contain a current ThingSpace authorization bearer token and a valid VZ-M2M session token and must set the content-type to JSON.
Parameter Name |
Data Type |
Description |
Authorization (required) |
string |
HTTP Authorization bearer token. |
VZ-M2M-Token (required) |
string |
A valid session token returned by
|
Content-Type (required) |
string |
Must be |
The body contains the account name and list of devices that are to be located, plus other options.
Property Name |
Data Type |
Description |
accountName (required) |
string |
The name of a billing account which is usually in the format of 10 digits, a hyphen and then five more digits. 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:
|
deviceList (required) |
array of device identifier objects |
Each object in the array identifies a device that you want to locate:
Note: the Note: |
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.
|
{
"accountName": "2234434445-32333",
"accuracyMode": "1",
"cacheMode": "2",
"maxLocAge": 120,
"deviceList": [
{"id": "354677790348290", "kind": "imei", "mdn": "5557337468"}
]
}
Status 200
A successful response returns a unique transaction ID that can be used to associate callback messages with the original request:
Parameter Name |
Data Type |
Description |
transactionID |
string |
A unique string 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 |
enum |
QUEUED |
Example Respones, Status 200
{
"transactionID": "4be7c858-0ef9-4b15-a0c1-95061456d835",
"status": "QUEUED"
}
Example Response, Status 400
All error messages are returned in this format:
{
"errorCode": "INVALID_PARAMETER",
"errorMessage": "Unregistered account"
}
Error codes and messages are listed on the Error Codes page, along with explanations and suggestions for corrective actions.
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 name of a billing account which is usually in the format of 10 digits, a hyphen and then five more digits. Any leading zeros must be included |
id (required) |
string |
A device identifier value |
kind (required) |
string |
The type of the identifier (example: IMEI) |
mdn (required) |
string |
The Mobile Directory Number (MDN) of the device. |
positionData (optional) |
position data object |
Will be empty if position data is not available for the device. |
positionData.x (required) |
string |
The X coordinate (latitude) of the device in decimal degree format. |
positionData.y (required) |
string |
The Y coordinate (longitude) of the device in decimal degree format. |
positionData.radius (required) |
string |
The radius of the location precision, in meters. A smaller radius indicates a more precise location. |
positionData.qos (optional) |
boolean |
Indicates if |
positionData.time |
string |
The time that the location was reported. If the request was for “cached or current” information (cacheMode=2), the time value can be used to determine if the location is cached or current data |
error (optional) |
position error object |
Will be empty if there was no error. If the location was not retrieved because the device was offline, an error appears. However, ThingSpace will attempt to retrieve a location as soon as it is reachable. |
error.type (required) |
string |
The error type. See error codes for a list of possible errors |
error.info (required) |
string |
Additional error information |
error.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
|
cachedReason (optional) |
string |
An integer (as a string) representing why the cached location returned
|
reportType (required) |
string |
A string representing the report the callback is reporting: |
status (required) |
string |
SUCCESS or FAILED |
transactionID (optional) |
string |
A unique string 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 Note: Not included for Device Initiated Locations, as they are generated without any transaction initiated from Network |
Example callback, SUCCESS
{
"accountName":"2234434445-32333",
"deviceList":[
{
"id":"354677790348290",
"kind":"IMEI",
"mdn":"5557337468",
"positionData":{
"cachedReason":"1",
"locationType":"0",
"radius":"487.0000000",
"time":"20201002204910",
"x":"32.8981133",
"y":"-117.1997910"
}
}
],
"reportType":"LOCATION_REPORT",
"status":"SUCCESS",
"transactionID":"bab409a2-cc8f-4391-aa3d-2a684a10ea99"
}
Example callback, FAILED
{
"accountName": "2234434445-32333",
"deviceList": [
{
"error": {
"info": "Specified device ID was excluded from using the service",
"time": "20201002005827",
"type": "TS CONSENT CHECK FAILED"
},
"id": "354677790348290",
"kind": "IMEI",
"mdn": "9883926165"
}
],
"reportType": "LOCATION_REPORT",
"status":"FAILED",
"transactionID": "2a076c21-8dc6-430a-81fe-b0a50c372528"
}
Status 200:
Success Response with no body.