Topic Data API

This API endpoint allows 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.

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)
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
unit Unit of measurement for values collected for this topic