POST /locationsReturns the location of up to 20 devices, including latitude, longitude, and a radius that indicates the accuracy of the location. If more than 20 devices need to be located, use POST /locationreports.
See also:
Create a Device Location Report
Exclude devices so they can’t be located
Get location service subscription status
About Location Information
This method can only be used to locate IoT and Fixed Wireless Access (FWA) devices.
You can request a device’s current location, or request the previous location from the cache. 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 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 for up to 30 days of the original request. To be notified when the device is reachable, use the Reachability API. The Extended Diagnostic API can be used subsequently to retrieve the updated location ThingSpace retrieved from the network.
POST https://thingspace.verizon.com/api/loc/v1/locations
None.
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 POST /api/m2m/v1/session/login. |
| Content-Type required |
string | Must be application/json. |
The body contains the the account name and list of devices that you want to locate, 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. Must include any leading zeros. |
| accuracyMode optional |
string | An integer (as a string) representing the requested accuracy of the returned location. Coarse location (0) is currently the only supported value.
|
| 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 | The devices that you want to locate. The array cannot contain more than 20 devices. |
| deviceList.id required |
string | a device identifier value |
| deviceList.kind required |
string | the type of the identifier (IMEI, MEID, or ESN) |
| deviceList.mdn required |
string | the 10-digit “phone number” of the device (you can remove the 1 from the beginning of an MSISDN to derive the MDN) |
{
"accountName": "1234567890-00001",
"accuracyMode": "0",
"cacheMode": "1",
"deviceList": [
{"id": "900000000000009", "kind": "imei", "mdn": "10-digit phone number"},
{"id": "900000000000019", "kind": "imei", "mdn": "10-digit phone number"}
]
}
Status 200
A success response is an array of JSON objects, each containing the position data or an error for a device in the request.
| Property Name | Data Type | Description |
|---|---|---|
| msid | string | The MDN of the device. |
| pd | position data object | Will be empty if position data is not available for the device. |
| pd.x | string | The X coordinate (latitude) of the device in decimal degree format. |
| pdy | string | The Y coordinate (longitude) of the device in decimal degree format. |
| pd.radius | string | The radius of the location precision, in meters. A smaller radius indicates a more precise location. |
| pd.time | string | The time that the location was reported. If the request was for “cached or current” information (cacheMode=2), the time value will tell you whether the location is cached or current data. |
| pd.utcoffset | string | The UTC offset of the time; omitted if the offset is 0. |
| error | position error object | 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. |
| error.type | string | The error type. |
| error.info | string | Additional error information. |
| error.time | string | The time that the error was reported. |
| error.utcoffset | string | The UTC offset of the time; omitted if the offset is 0. |
[
{
"msid": "7892345678",
"pd":{
"time": "20170520004421",
"x": "33.45324",
"y": "-84.59621",
"radius": "5571",
"qos": "false"
},
"error": {}
},
{
"msid": "8583239709",
"pd":{
"time": "20170525214342",
"x": "38.8408694",
"y": "-105.0422583",
"radius": "3866",
"qos": "false"
},
"error": {}
},
{
"msid": "7897654321",
"pd": {},
"error": {
"time": "20170525214342",
"type": "POSITION METHOD FAILURE",
"info": "Exception code=ABSENT SUBSCRIBER"
}
}
]
Status 400
Status code 400 is only returned for unexpected errors, such as invalid parameters. All error messages are returned in this format:
{
"errorCode": "The type of error, such as INVALID_REQUEST.",
"errorMessage": "Additional error information."
}
Error codes and messages are listed on the Error Codes page, along with explanations and suggestions for corrective actions.