Create a Device Location Report:

`POST /locationreports`

Requests generation of an asynchronous location report for up to 10,000 devices. This request returns a transaction ID that can be used to check on the status of the report, retrieve the report, or cancel the report. Reports are available for 30 days.

Create a Device Location Report:
POST /locationreports

Uses and Requirements

IoT / FWA Devices Only

This method can only be used to locate IoT and Fixed Wireless Access (FWA) devices.

Current or Cached Location

You can request a report of current device locations, or request the previous locations from the cache. If you request cached device location information, the report will be ready immediately and you can use the transaction ID from the response to retrieve it. If you request current device location information, it may take time for the report to be created; you can use the transaction ID to get the report status, and then to retrieve the report when it is ready.

Polling or Callback Notifications

A device management system can be coded so that it receives callback messages when asynchronous reports are ready, or it can poll to check the status of reports.

Location Accuracy

The requested accuracy may or may not be met due to device capability and other network restrictions. The report will have a qos (Quality Of Service) parameter to indicate if the requested accuracy was met.

Reachability

The device needs to be powered on and connected to the network to retrieve the location. ThingSpace will store the last known (successful) location within the Extended Diagnostics API. If the device is offline or otherwise unreachable, the request status will likely fail and show an error. However, as soon as the device powers on and connects to the network, ThingSpace will retry to retrieve the location. To be notified when the device is reachable, use the Reachability API. The Extended Diagnostic API can be called subsequently to retrieve the updated location ThingSpace retrieved from the network.

Request Components

HTTP Request

POST https://thingspace.verizon.com/api/loc/v1/locationreports

Resource Path and Query Parameters

None.

Header Parameters

The request header must contain a current ThingSpace authorization bearer token and a valid VZ-M2M session token, and must set the content-type to JSON.

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.
Content-Type required	string	Must be `application/json`.

Request Body

The body contains the the account name and list of devices that you want to locate, plus other options.

Property Name	Data Type	Description
accountName required	string	The name of a billing account, which is usually in the format of 10 digits, a hyphen, and then five more digits. Must include any leading zeros.
accuracyMode optional	string	An integer (as a string) representing the requested accuracy of the returned location. Coarse location (0) is currently the only supported value. 0: coarse accuracy 1: Reserved for future enhancements
cacheMode optional	string	An integer (as a string) indicating whether current or cached location information should be returned. 0: Cached. (Default) Information from the last successful device location check is returned, or an error message is returned if there is no cached information for a device. There is no billing charge for requesting cached location information. 1: Cached or current. ThingSpace first looks for cached information for the device and returns that if it exists. If there is no cached information, it finds the current location of the device and returns that information, plus stores it in the cache. 2: Current. Returns the current location of the device, and stores that location information in the cache.
deviceList required	array of device identifier objects	Each object in the array must contain three elements that identify a device that you want to locate: id: a device identifier value kind: the type of the identifier (IMEI, MEID, or ESN) mdn: the 10-digit “phone number” of the device (you can remove the 1 from the beginning of an MSISDN to derive the MDN)

Example Request Body

{
  "accountName": "1234567890-00001",
  "accuracyMode": "0",
  "cacheMode": "1",
  "deviceList": [
    {"id": "900000000000009", "kind": "imei", "mdn": "10-digit phone number"},
    {"id": "900000000000009", "kind": "imei", "mdn": "10-digit phone number"}
  ]
}

Success Responses

Status 200

Requests with cacheMode=0 return a 200 status and the report is available immediately. Requests with cacheMode=1 or 2 return a 200 status, and the body of the request includes an estimate of how long it will take to create the report.

Success responses return a transaction ID that you can use to retrieve the report, get the status of the report, or cancel the report.

Property Name	Data Type	Description
txid	string	Unique ID of the request.
status	enum	QUEUED or COMPLETED
estimatedDuration	string	Estimated number of minutes required to complete the report.

Example Success Response

{
  "txid": "2c90bd28-ece4-42ef-9f02-7e3bd4fbff33",
  "status": "QUEUED",
  "estimatedDuration": "12"
}

Failure Responses

Status 400

Status code 400 is returned for invalid parameters and unexpected errors. 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!