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 you can use to check on the status of the report, retrieve the report, or cancel the report. Reports are available for 30 days.


See also:
Get Device Location Report Status
Retrieve a Device Location Report
Cancel a Device Location Report
Find Device Locations
Register a Callback Listener
About Location Information

Uses and Requirements

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

You can code your device management system 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.

Request Components

HTTP Request


Resource Path and Query Parameters


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
string HTTP Authorization bearer token.
string A valid session token returned by POST /api/m2m/v1/session/login.
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
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.
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
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.
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": "980003420535573", "kind": "imei", "mdn": "7892345678"},
    {"id": "375535024300089", "kind": "imei", "mdn": "7897654321"},
    {"id": "A100003861E585", "kind": "meid", "mdn": "7897650914"}

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.