Retrieve a Device Location Report
Retrieve a Completed Location Report
GET /locationreports/{accountName}/report/{txid}/index/{startindex}
Returns a generated device location report that was created with a POST /locationreports request. Reports are available for 30 days once generated. Each response includes a maximum of 1,000 devices. If the report contains more than 1,000 devices (indicated by the hasMoreData parameter in each response), send additional requests to retrieve the remaining devices. Use the startIndex parameter to return a different set of devices in each response.
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
Request Parameters
The accountName and transaction ID (txid) must be included in the path to identify the report as well as the startIndex to specify the starting record.
| Parameter Name | Data Type | Description |
|---|---|---|
| accountName (required) | string | The numeric name of the account that the report was requested for. |
| txid (required) | string | The transaction ID from the POST /locationreports response. This si a 32 or 36-bit UUID. |
| startIndex (required) | integer | The zero-based number of the first record to return. Set "startIndex": "0" for the first request. If there are more than 1,000 devices to be returned ("hasMoreData": true), set "startIndex": "1000" for the second request and "startIndex": "2000" for the third request, and so on, until all records are retrieved. |
Request Body
None.
Success Response
Status 200 A success response includes information about the report itself (transaction ID, number of device records returned and which page is displayed) and an array of objects, each containing the position data or an error for a device in the request. Example Success Response
{
"startIndex":"0",
"txid":"2017-12-11Te8b47da2-eeee-ffff-gggg-61815e1e97e9",
"totalCount":"3",
"hasMoreData":false,
"devLocationList":[
{
"error": {},
"msid": "10-digit phone number",
"pd":{
"qos": "false",
"radius": "5571",
"time": "20170520004421",
"x": "33.45324",
"y": "-84.59621"
}
},
{
"error": {},
"msid": "10-digit phone number",
"pd":{
"qos": "false",
"radius": "3866",
"time": "20170525214342",
"x": "38.8408694",
"y": "-105.0422583"
}
},
{
"error": {
"time": "20170525214342",
"type": "POSITION METHOD FAILURE",
"info": "Exception code=ABSENT SUBSCRIBER"
},
"msid": "10-digit phone number",
"pd": {}
}
]
}Success Parameters
| Property Name | Data Type | Description |
|---|---|---|
| startIndex | string | If "hasMoreData": true, add 1000 to this value to use for startIndex in the next request to retrieve the next block of 1000 locations in the report. |
| txid | string | The transaction ID of the report. |
| totalCount | integer | The total number of devices in the request and in the report. Note: Each response includes a maximum of 1000 devices. |
| hasMoreData | Boolean | This will be true if there are more device locations to retrieve. If there are less than 1000 total devices, this will be false. |
| devLocationList | array | Device location information. |
| msid | string | The Mobile Services ID of the device. This is a 10-digit phone number. |
| 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 the Quality of Service (QoS) target is met. Default is currently false. |
| time | string | The time that the location was reported. If the request was for “cached or current” information, there will be a cacheMode value that will indicate whether the time at the location is cached (2), cached or current (1) or current data (0). |
| utcoffset | string | The UTC offset of the time; omitted if the offset is 0. |
| error | object | Position error. This will be empty if there was no error; if there is an error, this object will contain the error type, information about the error and the time the error ocurred. 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 UTC offset of the time, omitted if the offset is 0. |
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.