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

• Uses and Requirements
  • IoT devices can only be located by the account that owns them
  • End-user consent required to locate devices
  • Current or Cached Location
  • Number of Periodic location reports
  • Interval between location reports
  • Option to start periodic location immediately or after some time the request is received
• Request Components
  • HTTP Request
  • Resource Path and Query Parameters
  • Header Parameters
  • Request Body
    • Example Request Body
  • HTTP Response
    • HTTP Response Examples
• locationReport Callback Parameters
• Success Response
  • Asynchronous Callback
    • Example callback containing device location information
    • Example callback when device location could not be provided

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.

End-user consent required to locate devices

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.

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:

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

• Uses and Requirements
  
  • Periodic location sessions can only be stopped by the account that owns the devices
  • Maximum of 100 MDNs per request
• Request Components
  • HTTP Request
  • Resource Path and Query Parameters
  • Header Parameters
• HTTP Response
  • HTTP Response Examples
• stopPeriodicDeviceLocations Callback Parameters
  • Example Callback

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

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.

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:

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:

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