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
/sotixsight/api/liveview
Type: POST
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 |
|
Shared Topics/Events | $topicKey = <packageId>/<field
key> |
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
Device Attribute | Token ($deviceProperty) |
---|---|
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 |
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
|
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,…
- 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 |