Get Device Location - Asynchronous

Obtain the location of IoT Devices (asynchronous)

POST /devicelocations

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

Contents

Obtain the location of IoT Devices (asynchronous) POST /devicelocations

See also:

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

 

Uses and Requirements

Devices can only be located by the account that owns them

Only the account that owns the devices being queried is allowed to request their location.

For IoT devices, the device owner must give their consent for the device location information to be determined and reported. When a location request is sent for an IoT 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 or consent is denied, ThingSpace will not proceed further to compute the location information of the device and a callback will be sent with an error. If the account owner gives consent (or if there is already a current consent), the location information will be returned in a callback message

Current or Cached Location

You can request a device’s current location, or request the previous location from the cache. Customer can specify maxLocAge to specify the age of the location that can be accepted for cached location (this is used when cacheMode is set to “Cached or current”). 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 (for “Coarse” only). The Customer can ask for “Coarse” or “Precise” accuracy using the accuracyMode.

Back to Top

Request Components

HTTP Request

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

Resource Path and Query Parameters

None.

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

Back to Top

Request Body

The body contains the account name and list of devices that are to be located, 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. Any leading zeros must be included

accuracyMode (optional)

string

An integer (as a string) representing the requested accuracy of the returned location: 0: coarse accuracy, 1: precise accuracy, 2: 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 (Ignore maxLocAge and just return cached location)
  • 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, then stores it in the cache (A location within maxLocAge if available is returned, if not then a current location is triggered)
  • 2 - Current. Returns the current location of the device and stores that location information in the cache (Ignore maxLocAge and just return current location)

deviceList (required)

array of device identifier objects

Each object in the array identifies a device that you want to locate: [ deviceList.deviceIds.kind, deviceList.deviceIds.id ]

  • id: A device identifier value
  • kind: The type of the identifier, IMEI, MEID, or ESN

 

Note: the kind has to be the same across the list; mixed kind is not supported today

Note: deviceList can contain maximum of 10000 devices

maxLocAge (optional)

string

An integer (as a string) indicating maximum tolerable age in seconds of position estimates used for cached position fixes if another position was computed due to another request.

  • Range: 0 to 3600 seconds
  • Default: 120 seconds (if not specified).

 

Example Request Body

{

  "accountName": "2234434445-32333",

  "accuracyMode": "1",

  "cacheMode": "2",

  "maxLocAge": 120,

  "deviceList": [

    {"id": "354677790348290", "kind": "imei", "mdn": "5557337468"}

  ]

}

Back to Top

HTTP Response

Status 200
A successful response returns a unique transaction ID that can be used to associate callback messages with the original request:

Parameter Name

Data Type

Description

transactionID

string

A unique string that associates the request with the device location information that is sent in an 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 transactionID

status

enum

QUEUED

 

Example Respones, Status 200

{

    "transactionID": "4be7c858-0ef9-4b15-a0c1-95061456d835",

    "status": "QUEUED"

}

 

Example Response, Status 400
All error messages are returned in this format:

{

    "errorCode": "INVALID_PARAMETER",

    "errorMessage": "Unregistered account"

}

Error codes and messages are listed on the Error Codes page, along with explanations and suggestions for corrective actions.

 

Back to Top

locationReport Callback Parameters

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

Parameter 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. Any leading zeros must be included

id (required)

string

A device identifier value

kind (required)

string

The type of the identifier (example: IMEI)

mdn (required)

string

The Mobile Directory Number (MDN) of the device.

positionData (optional)

position data object

Will be empty if position data is not available for the device.

positionData.x (required)

string

The X coordinate (latitude) of the device in decimal degree format.

positionData.y (required)

string

The Y coordinate (longitude) of the device in decimal degree format.

positionData.radius (required)

string

The radius of the location precision, in meters. A smaller radius indicates a more precise location.

positionData.qos (optional)

boolean

Indicates if QOS is met (for Coarse Location only)

positionData.time

string

The time that the location was reported. If the request was for “cached or current” information (cacheMode=2), the time value can be used to determine if the location is cached or current data

error (optional)

position error object

Will be empty if there was no error

error.type (required)

string

The error type. See error codes for a list of possible errors

error.info (required)

string

Additional error information

error.time (required)

string

The time that the error was reported

locationType (optional)

string

An integer (as a string) representing whether the cached or current location returned

  • 0 - cached
  • 1 - current

cachedReason (optional)

string

An integer (as a string) representing why the cached location returned

  • 0 - user requested cache
  • 1 - location computed within maxLocAge available

reportType (required)

string

A string representing the report the callback is reporting: CONSENT_RESPONSE, LOCATION_REPORT or STOP_PERIODIC_LOCATION_RESPONSE

status (required)

string

SUCCESS or FAILED

transactionID (optional)

string

A unique string that associates the request with the location report information that is sent in an asynchronous callback message. ThingSpace will send a separate callback message for each device that was in the request. All of the callback messages for the same device will have the same transactionID

Note: Not included for Device Initiated Locations, as they are generated without any transaction initiated from Network

Back to Top

Example callback, SUCCESS

{

   "accountName":"2234434445-32333",

   "deviceList":[

      {

         "id":"354677790348290",

         "kind":"IMEI",

         "mdn":"5557337468",

         "positionData":{

            "cachedReason":"1",

            "locationType":"0",

            "radius":"487.0000000",

            "time":"20201002204910",

            "x":"32.8981133",

            "y":"-117.1997910"

         }

      }

   ],

   "reportType":"LOCATION_REPORT",

   "status":"SUCCESS",

   "transactionID":"bab409a2-cc8f-4391-aa3d-2a684a10ea99"

}

 

Example callback, FAILED

{

  "accountName": "2234434445-32333",

  "deviceList": [

    {

      "error": {

        "info": "Specified device ID was excluded from using the service",

        "time": "20201002005827",

        "type": "TS CONSENT CHECK FAILED"

      },

      "id": "354677790348290",

      "kind": "IMEI",

      "mdn": "9883926165"

    }

  ],

  "reportType": "LOCATION_REPORT",

  "status":"FAILED",

  "transactionID": "2a076c21-8dc6-430a-81fe-b0a50c372528"

}

Status 200:
Success Response with no body.

Back to Top