# 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](https://thingspace.verizon.com/documentation/api-documentation.html#/http/session-management/guides/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 [GET https://thingspace.verizon.com/api/loc/v1/locationreports/{accountName}/report/{txid}/index/{startindex}](/docs/premium-apis/device-location/api-endpoints/devices-locations/retrievelocationreport) ## 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 ```json { "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: ```json { "errorCode": "The 3-digit HTML error code", "errorMessage": "string" } ``` Error codes and messages are listed on the [Error Codes page](https://thingspace.verizon.com/documentation/api-documentation.html#/http/device-location/error-codes), along with explanations and suggestions for corrective actions.