Topic Data API

This API endpoint enables users to be able to retrieve standard and shared topic/event metadata or values from devices in real time

Endpoint: 
/sotixsight/api/liveview

Type: POST

Request Headers: 
Authorization: Bearer $access_token

Replace $access_token according to it’s description:

Key descriptions:

Key Description
$access_token OAuth 2.0 Access Token required to authenticate (see XSight OAuth 2.0 Access Token).

Retrieving Topic Values

Request Body:

Format request as plaintext:

"SELECT $topicKeys FROM $deviceFilters WHERE $conditions"
Or as JSON:
{
    "query": "SELECT $topicKeys FROM $deviceFilters WHERE $conditions"
}

Replace variables in the Request Body with the following:

$topicKeys

  • One or more topics are required for the request to be valid.

Format: $topicKey,$topicKey,…

Topic Type Format
Standard Topic

$topicKey = <standard topic key>
Shared Topics/Events $topicKey = <packageId>/<field key>
Note: Topic keys are comma separated.
Standard Topic Key Topic Id (tId) Topic Name (msg) Display Unit (dispUnit) Description
loclatlong 0 Lat/Long Latitude and longitude of the device's location
cpu 1 CPU % Percentage of the device's CPU being used
memused 2 Used Memory % Percentage of the device's memory being used
speedkmh 5 Speed (km/h) km/h Speed of the device in kilometers per hour
speedmph 6 Speed (mph) mph Speed of the device in miles per hour
storused 8 Used Storage % Percentage of storage used on the device
battlvl 40 Battery Level % Battery level of the device
batthealth 41 Battery Health % Battery health of the device
battchrgntchg 42 Battery Charge (Net Change) %/h Net percentage gain over the hour
battchrgtotdrp 43 Battery Charge (Total Drop) % Total drop in charge over the last hour
battchrgtotgn 44 Battery Charge (Total Gain) % Total gain in charge over the last hour
battchrgevnt 45 Battery Charge Event Event with Net, Drop and Gain fields
battcap 46 Battery Capacity mAh Current capacity of the battery
appforg 50 Foreground App Event capturing the change of app that is currently in the foreground
drpshrly 60 Hourly Drops Number of device drops over the last hour
drpstot 61 Total Drops Number of device drops over the last day
virscndt 62 Virus Scan (date) Last date of Virus Scan by the SOTI MobiControl Agent
reboots 63 Device Reboots Number of device reboots over the last hour
drpsevnt 70 Device Drop Event Event capturing a device drop
netswtchs 80 Network Switches Event capturing a change in a device's Wi-Fi or cellular connection
cellsig 90 Cell Signal % Current cellular signal strength given as a percentage
cellnettyp 91 Cell Network Type Current cellular network type
cellband 92 Cell Band Current cellular band
cellsinr 93 Cell SINR dB Current cellular signal to-noise-ratio
cellrsrp 94 Cell RSRP dBm Current reference signal received power
cellrsrq 95 Cell RSRQ dB Current reference signal received quality
wifisig 110 Wi-Fi Signal % Current Wi-Fi signal strength given as a percentage

Examples:

  • CPU, Shared Topic from com.ambulance.app with field key o2, Battery Level (%):

    cpu,com.ambulance.app/o2,battlvl

  • Shared Topic from com.delivery.truck with field key inv, CPU, Battery Level:

    com.delivery.truck/inv,cpu,battlvl

  • Shared Topics from com.delivery.truck with field key inv & fuel, CPU, Battery Level:

    com.delivery.truck/inv,com.delivery.truck/fuel,cpu,battlvl

  • Lat/Long, Cell Signal(%), Wi-Fi Signal (%), Cell Net Type, Cell Band:

    loclatlong,cellsig,wifisig,cellnettyp,cellband

$deviceFilters

Device Attributes

  • Format: $deviceFilter = $deviceProperty $operator $argument
Supported Query Fields
Device Attribute Token ($deviceProperty)
MobiControl Instance Name mcName
Device Path dPath
Device Id dId
Device Name dName
Device Group dGrp
Mnufacturer mfg
Model model
MAC Address mac
IP Address ip
OS Name os

Combining Filters

  • Combine device filters using the AND.

    $deviceFilter1 AND $deviceFilter2

Operators

Operator Syntax
Equals $token = $str
Not Equals $token != $str
Contains $token CONTAINS $str
Not Contains $token !CONTAINS $str
Starts With $token STARTSWITH $str
Not Starts With $token !STARTSWITH $str
Ends With $token ENDSWITH $str
Not Ends With $token !ENDSWITH $str
Include $token IN $str
Not Include $token !IN $str
$deviceFilter Example:
  • dfg IN (‘Zebra’, ‘Honeywell’) AND dGrp CONTAINS ‘Cargo 001’

$conditions

The only condition supported for now is relative time (relTime). Request must specify time range for which the values are gathered.

Format:

relTime=(<startTime>,<endTime>)

  • Unit of measurement for <startTime> and <endTime>: seconds

$conditions Examples:

  • Send all data collected exactly two minutes ago

    relTime=(-120,-120)

  • Send all data collected from two minutes ago until one minute ago

    relTime=(-120,-60)

  • Send the first data point that’s more than two minutes old

    relTime=(0,-120)

Response Headers:

Status Code: $status_code
Status Code Description
200 Success
400 Bad Request
401 Unauthorized

Response Body:

{
    "devLst": [
        {
            "dId": "$deviceId",
            "dName": "$deviceName",
            "tLst": [{"tId": $tId, “vlist": [{"t": $t, "v": $v}]}]
        }
    ]
}

The Response Body contains a list of devices that have responded to the API Request. For each device, we provide the device Id dId, device name dName and a list of topics tLst that were requested. For each topic in the list of topics, we provide it's topic id tId and the list of values vlist. See the table below for a description for each key:

Key Description
devLst List of devices that matched the $deviceFilters and responded to the data request within the timeout.
dId Device Id.
dName Device Name.
tLst List of valid topics requested for in the Request Body in the $topicIdentifiers.
tId Topic Id for data corresponding to the topic list.
vlist List of time and value pairs for corresponding topic.
t Time when value v was collected.
v When the data returned is for a Shared Topic, this field contains the value collected at the corresponding time t.

When the data returned is for a Shared Event, this field is a JSON represented as a string. The JSON will contain name n and value v pairs representing the data collected at the corresponding time t. In plaintext the following characters will be escaped:

  • " as \"
  • \ as \\

n: Name corresponding with value v.

v: Value corresponding with time t.

Retrieving Topic Metadata

Request Body:

Format request as plaintext:

"SELECT $topicProperties FROM topics WHERE $topicConditions"

Or as JSON:

{
    "query": "SELECT $topicProperties FROM topics WHERE $topicConditions"
}

Replace variables in the Request Body with the following:

$topicProperties

  • One or more topic properties are required for the request to be considered valid.

Format: $topicProperty,$topicProperty,…

Note: Keys are comma separated.
$topicProperties Examples:
  • Topic Name, Topic Name and Package Id

    tId,msg,pid

  • Topic Name, Topic Name, Display Units and Package Id

    tId,msg,dispUnits,pid

$topicConditions

The only condition supported for now is the Topic Id. Request must specify one or more Topic Ids for the request to be considered valid.

Operators:

Operator Format
Equals tId = $topidId
Include tId IN ($topicId, $topicId,…)

$topicConditions Examples:

  • Query for the CPU Standard Topic

    tId = 1

  • Query for the CPU, Used Memory and O2 (a shared topic)

    tId IN (1,2, 5013)

Response Headers:

Status Code: $status_code
Status Code Description
200 Success
400 Bad Request
401 Unauthorized

Response Body:

{
    "tLst": [
        {
            "tId": "$topicId",
            "msg": "$msg",
            ...
        }
    ]
}

The Response Body contains a list of topics (tLst) that data have been requested for. For each topic, we return the requested topic properties. Mapping of Property Keys to Description:

Property Key Description
tLst List of topics that matched $tIdConditions from the Request Body.
tId Topic Id
dTyp Topic Data Type
disp Display type, is the topic displayable on the UI.
eFlg Error Flag
fr Frequency
ranges Mapping color
pid Package Id
sc Significant change
key Topic Key
msg Topic Name
typ Topic Type
dispUnit Unit of measurement for values collected for this topic