Periodic Device Location

Periodic Device Location

Start periodic location of devices (asynchronous):

POST /devicelocations/action/periodic

Starts the periodic location of up to 10,000 devices (for Precise Location only). This request returns a synchronous transaction ID and the location information for each device is returned asynchronously as a DeviceLocation callback message.

Contents

Start periodic location of devices (asynchronous): POST /devicelocations/action/periodic

See also:
Register a Callback Listener
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

The Device Owner can request a device’s current location or request the previous location from the cache. The Device Owner can specify maxLocAge to specify the age of the location that can be accepted for a 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.

Number of Periodic location reports

The Device Owner can specify the number of location reports (numberOfFixes) after which the periodic location can be stopped. If this is not specified (it’s optional, not required) then periodic location will continue until stopped by the Device Owner.

Interval between location reports

The Device Owner can specify the interval between location reports (fixInterval) for periodic location. If this is not specified (it’s optional, not required) then the default interval will be used for sending periodic location information (see the table below).

Option to start periodic location immediately or at some time after the request is received

The Device Owner can specify if the periodic location session starts immediately or at some time (startTime) after the request is received by device. If this is not specified (it’s optional, not required) then the default interval will be used (see the table below).

Back to Top

Request Components

HTTP Request

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

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

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

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)

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

Note: deviceList can contain a 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)

Note: If the field is present and a location within maxLocAge is available then the value is returned. If not then a current location is triggered

numberOfFixes (optional)

string

An integer (as a string) indicating the number of position fixes during the periodic triggered session

  • Range: 0 (infinite tracking) to 1000
  • Default: 12

Note: If this value is not provided or set to 0, Periodic Location will continue running until a “Stop” is received

fixInterval (optional)

string

An integer (as a string) indicating the interval in seconds between the start of position fixes for the periodic trigger

  • Range: 1 to 1036800 seconds (12 days max to accommodate max PSM sleep)
  • Default: 3600 seconds (1 hour)

startTime (optional)

string

An integer (as a string) indicating when the Device starts the first position fix. Start Time is interpreted relative to the current time (i.e. the time when the message containing the parameter is received by the device)

  • Range: 0 to 86400 seconds (maximum is delaying for 1 day before the request is started)
  • Default: 0 seconds

Note: If the resource is not provided or set to 0, the periodic fix request starts immediately

Example Request Body

{

  "accountName": "2234434445-32333",

  "maxLocationAge": 120,

  "deviceList": [

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

  ],

  "numberOfFixes": 4,

  "fixInterval": 60,

  "startTime": 25

}

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.ThingSpacewill 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 Response, 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.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

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

Example callback, SUCCESS

    "accountName":"2234434445-32333",

    "deviceList":[

        {

            "id":"354677790348290",

            "kind":"IMEI",

            "mdn":"5557337468",

            "positionData":{

               "locationType": "1",

               "radius":"1782",

               "time":"20200723030357",

               "x":"37.65996174987342",

               "y":"-122.46907314206896"

            }

        }

    ],

    "reportType":"LOCATION_REPORT",

    "status":"SUCCESS",

    "transactionID":"9d98e12b-5287-4db2-8b1b-f295ced4527e"

}

Example callback, FAILED

{

 "accountName": "2234434445-32333",>

   "deviceList": [

    {

      "error":

        "info": "Specified device category is not IoT",

        "time": "20201002010140",

        "type": "TS DEVICE TYPE CHECK FAILED"

      },

      "id": "354677790348290",

      "kind": "IMEI",

      "mdn": "5557337468"

    }

  ],

  "reportType": "LOCATION_REPORT",

  "status": "FAILED",

  "transactionID": "58ad1c75-f423-4987-adda-b171d7a18207"

}

Status 200:

Success Response with no body.

Back to Top

 

Stop periodic location of IoT devices (asynchronous):

DELETE /devicelocations/action/periodic

Stops the periodic location session of devices (for Precise Location only). This request returns a synchronous transaction ID and the status for each device is returned asynchronously as a DeviceLocation callback message.

Contents

Stop periodic location of devices (asynchronous): DELETE /devicelocations/action/periodic

See also:

Register a Callback Listener
About Location Information
About Callback Services

Uses and Requirements

Periodic location sessions can only be stopped by the account that owns the devices

Periodic location sessions for devices can only be obtained or cancelled by the account that owns those devices.

Maximum of 100 MDNs per request

The Customer can specify a maximum of 100 Mobile Directory Numbers (MDNs) per request for stopping periodic location sessions. Status of the stop request is sent as a callback, one per device.

Request Components

HTTP Request

DELETE https://thingspace.verizon.com/api/loc/v1/devicelocations/action/periodic/{transactionID}?{accountName}

Path Parameters

Parameter Name

Data Type

Description

transactionID (required)

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 associated with the same device will have the same transactionID

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

mdn (required)

array of strings

A list of MDNs, maximum of 100

Back to Top

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

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

COMPLETED

Example Respone, Status 200

{

    "transactionID": "595ffce4-c31c-4552-8670-020a1545a84d ",

    "status": "COMPLETED"

}

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

stopPeriodicDeviceLocations 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

transactionID (required)

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

deviceList (required)

Array of device identifier objects

Only one object with {kind or id} where the kind or id shall be same as the one in the initial request from the customer:

  • kind: the type of the identifier (IMEI)
  • id: a device identifier value

Note: One of these objects only

status (required)

string

SUCCESS

reportType (required)

string

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

Example callback response

{

   "accountName":"2234434445-32333",

   "deviceList":[

      {

         "id":"354677790348290",

         "mdn":"5557337468"

      }

   ],

   "reportType":"STOP_PERIODIC_LOCATION_RESPONSE",

   "status":"SUCCESS",

   "transactionID":"382fbeef-0000-4be4-a02b-e2faf5a41a35"

}

Status 200:
Success Response with no body

Back to Top