Find the location of devices:

POST /locations

Returns the location of up to 20 devices, including latitude, longitude, and a radius that indicates the accuracy of the location. If you need to locate more than 20 devices, use POST /locationreports.


See also:
Create a Device Location Report
Exclude devices so they can’t be located
Get location service subscription status
About Location Information

Uses and Requirements

Current or Cached Location

You can request a device’s current location, or request the previous location from the cache. Each request for a device’s current location overwrites the stored location in the cache.

There is no charge for retrieving a device’s cached location.

Location Accuracy

The requested accuracy may or may not be met due to device capability and other network restrictions. The response 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 The array cannot contain more than 20 devices. 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

A success response is an array of JSON objects, each containing the position data or an error for a device in the request.

Property Name Data Type Description
msid string The MDN of the device.
pd 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.
error 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

      "msid": "7892345678",
         "time": "20170520004421",
         "x": "33.45324",
         "y": "-84.59621",
         "radius": "5571",
         "qos": "false"
      "error": {}
      "msid": "8583239709",
         "time": "20170525214342",
         "x": "38.8408694",
         "y": "-105.0422583",
         "radius": "3866",
         "qos": "false"
      "error": {}
      "msid": "7897654321",
      "pd": {},
      "error": {  
         "time": "20170525214342",
         "type": "POSITION METHOD FAILURE",
         "info": "Exception code=ABSENT SUBSCRIBER"

Failure Responses

Status 400

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