POST /locations
Returns the location of up to 20 devices, including latitude, longitude, and a radius that indicates the accuracy of the location. If you need to locate more than 20 devices, 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
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 response will have a qos
(Quality Of Service) parameter to indicate if the requested accuracy was met.
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 array cannot contain more than 20 devices. Each object in the array must contain three elements that identify a device that you want to locate:
|
{
"accountName": "1234567890-00001",
"accuracyMode": "0",
"cacheMode": "1",
"deviceList": [
{"id": "980003420535573", "kind": "imei", "mdn": "7892345678"},
{"id": "375535024300089", "kind": "imei", "mdn": "7897654321"},
{"id": "A100003861E585", "kind": "meid", "mdn": "7897650914"}
]
}
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. |
x
|
string | The X coordinate (latitude) of the device in decimal degree format. |
y
|
string | The Y coordinate (longitude) of the device in decimal degree format. |
radius
|
string | The radius of the location precision, in meters. A smaller radius indicates a more precise location. |
qos
|
boolean | (Future use) Indicates if QOS is met. |
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. |
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. |
type
|
string | The error type. |
info
|
string | Additional error information. |
time
|
string | The time that the error was reported. |
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.