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.

Retrieve a completed location report:
GET /locationreports/{account}/report/{txid}/index/{startindex}

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

GET https://thingspace.verizon.com/api/loc/v1/locationreports/{account}/report/{txid}/index/{startindex}

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
account required	string	The name of the account that the report was requested for.
txid required	string	The transaction ID from the `POST /locationreports` response.
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, 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
Authorization required	string	HTTP Authorization bearer token.
VZ-M2M-Token required	string	A valid session token returned by POST /api/m2m/v1/session/login.

Request Body

None.

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.
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. 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.

Example Success Response

{
  "startIndex":"0",
  "txid":"2017-12-11Te8b47da2-3a45-46cf-9903-61815e1e97e9",
  "totalCount":"3",
  "hasMoreData":false,
  "devLocationList":[
    {  
      "error": {},
      "msid": "7892345678",
      "pd":{  
        "qos": "false",
        "radius": "5571",
        "time": "20170520004421",
        "x": "33.45324",
        "y": "-84.59621"
      }
    },
    {  
      "error": {},
      "msid": "8583239709",
      "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": "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.

Try It Out!