Get Device Location - Synchronous
Get the Location of devices (synchronous) - Coarse only
POST /locations
Returns the location of up to 20 devices; including latitude, longitude and a radius that indicates the accuracy of the location. To locate more than 20 devices, use POST /locationreports. This method can only be used for IoT and Fixed Wireless Access (FWA) devices.
Current or Cached Location A device’s current location can be requested 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.
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/locations
Request Parameters
| Property Name | Data Type | Description |
|---|---|---|
| accountName (required) | string | The numeric name of a billing account. 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. Valid values can be: 0: coarse accuracy, 1: 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. 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, ThingSpace finds the current location of the device and returns that information, plus stores it in the cache. 2: Current. Returns the current location of the device and stores that location information in the cache. |
| deviceList (required) | array | The devices to locate. The array cannot contain more than 20 devices and each object will have an id, kind and mdn. |
| id | string | A device identifier value. |
| kind | string | The type of the identifier. This will be an Internatonal Mobile Equipment ID (IMEI). |
| mdn | string | the 10-digit Mobile Directory Number or “phone number” of the device (Tip: Remove the "1" from the beginning of an MSISDN to derive the MDN). |
Request Body
The body contains the the account name and list of devices that you want to locate, plus other options. Example Request Body:
{
"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"
},
{
"id":"900000000000029",
"kind":"meid",
"mdn":"10-digit phone number"
}
]
}Success Response
Status 200 A success response is an array of objects, each containing the position data or an error for a device in the request. Example Success Response:
[
{
"msid": "10-digit phone number",
"pd":{
"time": "20240730004421",
"x": "33.45324",
"y": "-84.59621",
"radius": "5571",
"qos": "false"
},
"error": {}
},
{
"msid": "10-digit phone number",
"pd":{
"time": "20240730214342",
"x": "38.8408694",
"y": "-105.0422583",
"radius": "3866",
"qos": "false"
},
"error": {}
},
{
"msid": "10-digit phone number",
"pd": {},
"error": {
"time": "20240730214342",
"type": "POSITION METHOD FAILURE",
"info": "Exception code=ABSENT SUBSCRIBER"
}
}
]Success Parameters
| Property Name | Data Type | Description |
|---|---|---|
| msid | string | The Mobile Service ID, or phone number, of the device. |
| pd | object | Position Data. This 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 Quality of Service (QoS) is met. Current default is false. |
| time | string | The time that the location was reported. If the request was for “cached or current” information ("cacheMode": "1"), the time value will show whether the location is cached or current data. |
| utcoffset | string | The Coordinated Universal Time (UTC) offset of the time. This is omitted if the offset is 0. |
| error | object | Error type and details. 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 | string | The error type. |
| info | string | Additional error information. |
| time | string | The time that the error was reported. |
| utcoffset | string | The Coordinated Universal Time (UTC) offset of the time. This is omitted if the offset is 0. |
Failure Responses
Status code 400 is only returned for unexpected errors, such as invalid parameters. 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.