Get Device Locations - Asynchronous

Request the location of IoT or consumer devices (asynchronous):
POST /devicelocations

Requests the current or cached location of up to 10,000 IoT or consumer devices (phones, tablets. etc.). This request returns a synchronous transaction ID, and the location information for each device is returned asynchronously as a DeviceLocation callback message.

Contents

See also:
Cancel Asynchronous Device Location Request
Get Device Locations (synchronous)
Create a Device Location Report
Register a Callback Listener
Get location service subscription status
About Location Information
About Callback Services

Uses and Requirements

IoT and consumer devices cannot be in the same request

Each request can only contain either IoT devices or consumer devices; you cannot mix both types in the same request. Additionally, IoT devices can only be located by the account that owns those devices. An account requires special configuration to locate consumer devices.

For consumer devices, the device owner must give their consent for the device location information to be shared with third parties. When you send a location request for a consumer device, ThingSpace checks to see if there is a current consent for your account to access the specified device’s location. If there isn’t a consent on file, ThingSpace sends an SMS text message to the device asking the device owner to consent to share their location. + If the device owner gives consent (or if there is already a current consent), the location information will be returned in a callback message. + If they deny consent, the callback will contain an error. + If they do not reply to the consent message within an hour, ThingSpace will send a callback with an error. + If the device owner gives consent, but then later sends a “STOP” text to revoke consent, ThingSpace sends a callback to let your application know that consent has been revoked.

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. (“Coarse” accuracy is currently the only accuracy mode.)

Request Components

HTTP Request

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

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 identifies a device that you want to locate:
  • id: A device identifier value. Required for IoT devices; not needed for consumer devices.
  • kind: The type of the identifier, IMEI, MEID, or ESN. Required for IoT devices; not needed for consumer devices.
  • mdn: The 10-digit “phone number” of the device. Required for all devices in the request.
    (Remove the 1 from the beginning of an MSISDN to derive the MDN)

Example Request Body

Request for the current location of three consumer devices

{
  "accountName": "1223334444-00001",
  "accuracyMode": "0",
  "cacheMode": "2",
  "deviceList": [
    {"mdn": "7892345678"},
    {"mdn": "7897654321"},
    {"mdn": "7897650914"}
  ]
}

Request for the cached or current location of two IoT devices

{
  "accountName": "1234567890-00001",
  "accuracyMode": "0",
  "cacheMode": "1",
  "deviceList": [
    {"id": "375535024300089", "kind": "imei", "mdn": "4327654321"},
    {"id": "A100003861E585", "kind": "meid", "mdn": "4327650914"}
  ]
}

Success Response

Status 200

A success response returns a unique transaction ID that you can use to associate callback messages with the original request.

Property Name Data Type Description
txid string A unique string that associates the request with the device location information that is sent in asynchronous callback message.
ThingSpace will send a separate callback message for each device that was in the request. All of the callback messages will have the same txid.
status enum QUEUED or COMPLETED. Requests for IoT devices with cachemode=0 have status=COMPLETED; all other requests are QUEUED.

Asynchronous Callback

Each callback contains a single-device array that has the position data or an error for a device in the request.

Property Name Data Type Description
accountName string The name (number) of the account that originated the device location request.
txid string The unique ID that was in the synchronous response to the original request.
devLocationList array The position data or error information for a single device.
devLocationList.msid string The MDN of the device.
devLocationList.pd position data object Will be empty if position data is not available for the device.
devLocationList.pd.x string The X coordinate (latitude) of the device in decimal degree format.
devLocationList.pd.y string The Y coordinate (longitude) of the device in decimal degree format.
devLocationList.pd.radius string The radius of the location precision, in meters. A smaller radius indicates a more precise location.
devLocationList.pd.qos boolean (Future use) Indicates if QOS is met.
devLocationList.pd.time string The time that the location was reported. If the request was for “cached or current” information (cacheMode=2), you can use the time value to determine whether the location is cached or current data.
devLocationList.pd.utcoffset string The UTC offset of the time; omitted if the offset is 0.
devLocationList.error position error object Will be empty if there was no error.
devLocationList.error.type string The error type. See error codes for a list of possible errors.
devLocationList.error.info string Additional error information.
devLocationList.error.time string The time that the error was reported.
devLocationList.error.utcoffset string The UTC offset of the time; omitted if the offset is 0.

Example callback containing device location information

{
  "accountName": "string",
  "devLocationList": [  
    {  
      "msid": "7892345678",
      "pd":{  
        "time": "20180520004421",
        "x": "33.45324",
        "y": "-84.59621",
        "radius": "5571",
        "qos": "false"
      },
      "error": {}
    }
  ],
  "txid": "string"
}

Example callback when device location could not be provided

{
  "accountName": "string",
  "txid": "string",
  "devLocationList": [  
    {  
      "msid": "7897654321",
      "pd": {},
      "error": {  
        "time": "20180525214342",
        "type": "CONSENT REJECTED",
        "info": "Exception code=CONSENT REJECTED"
      }
    }
  ]
}

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!