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

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).

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

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