Retrieve a completed location report:

GET /locationreports/{account}/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.


See also:
Create a Device Location Report
Get Device Location Report Status
Cancel a Device Location Report

Uses and Requirements

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), you must send additional requests to retrieve the remaining devices. Use the startIndex parameter to return a different set of devices in each response.

Request Components

HTTP Request


Resource Path and Query Parameters

You must include the account name and transaction ID in the path to identify the report, and the startIndex to specify the starting record.

Parameter Name Data Type Description
string The name of the account that the report was requested for.
string The transaction ID from the POST /locationreports response.
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, 2000 for the third request, etc.

Header Parameters

The request header must contain a current ThingSpace authorization bearer token and a valid VZ-M2M session token.

Parameter Name Data Type Description
string HTTP Authorization bearer token.
string A valid session token returned by POST /api/m2m/v1/session/login.

Request Body


Success Responses

Status 200

A success response includes information about the report itself (number of devices, etc.) and an array of JSON objects, each containing the position data or an error for a device in the request. The order of the devices in the response is the same as in the original request.

Property Name Data Type Description
startIndex string If hasMoreData is true, the value to use for startIndex in the next request to retrieve the next block of 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 that each response includes a maximum of 1,000 devices.
hasMoreData Boolean True if there are more device locations to retrieve.
devLocationList array of objects Device location information.
string The MDN of the device.
position data object Will be empty if position data is not available for the device.
string The X coordinate (latitude) of the device in decimal degree format.
string The Y coordinate (longitude) of the device in decimal degree format.
string The radius of the location precision, in meters. A smaller radius indicates a more precise location.
boolean (Future use) Indicates if QOS is met.
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.
string The UTC offset of the time; omitted if the offset is 0.
position error object Will be empty if there was no error.
string The error type.
string Additional error information.
string The time that the error was reported.
string The UTC offset of the time; omitted if the offset is 0.

Example Success Response

      "error": {},
      "msid": "7892345678",
        "qos": "false",
        "radius": "5571",
        "time": "20170520004421",
        "x": "33.45324",
        "y": "-84.59621"
      "error": {},
      "msid": "8583239709",
        "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": "7897654321",
      "pd": {}

Failure Responses

Status 400

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.