Retrieve Device Location Report

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.

Contents

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

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