Customer API - Search
Thingstream provides a rich Customer API to allow you to carry out the majority of functions that can be done in the portal like changing the status of a Thing, or swapping to a different connectivity plan.
Here we are going to provide some hints and tips on Searching for "Things"
You'll find the API documentation for Search on Swagger. The access key and secret required for authentication can be found by selecting "Show Access Keys" under Settings/Domain Settings
In this section
Still need help?
If you need more help or have any questions, please send an email to services-support@u-blox.com
The search endpoint provides a powerful request payload that can be used in a number of ways to obtain details of one or more Things.
Below is an example of the default request payload:
{
"query": "string",
"sortField": "NAME",
"sortDirection": "ASC",
"filters": [
{
"filterField": "TYPE",
"value": {}
}
],
"count": 50,
"offset": 0
}
Search can be used to search for details on a:
specific device ("query")
number of devices by type alone ("filterField")
number of devices by state ("filterField")
number of devices by plan ("filterField")
number of devices by type and state (multiple "filterField" values)
sortField - allows you to specify a range of fields on which the response set can be sorted in either ascending or descending order. sortFields include (NAME, ID, TYPE, CONNECTED, SEEN, STATE, CREATED, HARDWARE_CODE, ENROLLED)
count - specifies the number of items that are returned in the response. The maximum value of count + offset will be 10k.
offset - to be used if you wish to batch query. e.g. set to 50, 50 things following the first 50 would be returned i.e. from 51 - 100
Search for a Specific Device
{
"query": "string",
"sortField": "NAME",
"sortDirection": "ASC",
"count": 50,
"offset": 0
}
When searching for a specific device we can use a variety of terms in the query string. We have removed the filters as the query string should be all we need.
Search by Identity
You may have the device identity and wish to obtain more details about the device including usage, in which case you update the above template as follows
"query":"device:5911xxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
In this case you could also adjust the count from 50 to 1 as only a single device should satisfy a query for a specific device identity
Search by Name
You may only know all or part of the name of a device and that can be used as well. The results here will be governed largely by the naming structure of your devices. For example you may have multiple SARA R422 Things. They may include things named as follows 'R422 Click', 'R422 Lower Garden', 'R422 Lower Terrace'.
You may know that the name of the thing you wish to find has R422 in it but not sure which it is, in which case you may do as follows:
"query":"R422"
and details of all three Things would be returned.
"query":"R422 Lower" would return details of just two of the above named Things.
Search by Hardware Id
As with identity and name other attributes of the Thing being searched for may be used in the query field.
For example you may have a hardware Id or even part of a hardware Id and these may be used in the query field. This is useful if you have a large number of SIM based things that were ordered together and the hardware numbers run sequentialy.
"query" : "894xxxxxxxxxxxxxxxx"
Search by Tag
Where you have applied tags to your devices, you may search for a single or rang eof devices based on that tag. If you have grouped devices in a generalised region and then tagged them for example North, South, East, West, you may use this tag in the "query" field
"query":"north"8944500909208895985
Search for Device by Type
{
"sortField": "NAME",
"sortDirection": "ASC",
"filters": [
{
"filterField": "TYPE",
"value": {}
}
],
"count": 50,
"offset": 0
}
When searching for a device by Type we specify the filterField to be Type. We have removed the "query" field as this is a general search.
Type values are specified as the device type which are listed next to the device and may be mapped to one of the following
THINGSTREAM_SIM, THINGSTREAM_INTERNET, THINGSTREAM_LORA, MQTT_FLEX, CLOUDLOCATE_GNSS, CLOUDLOCATE_S2S, CELLLOCATE_S2S, POINTPERFECT, POINTPERFECT_S2S, RTCM, POINTSAFE, ASSIST_NOW_OFFLINE_TOKEN, ASSIST_NOW_ONLINE_TOKEN, SPOTNOW
Search for all SIM things sorting by Last Seen Ascending
{
"sortField": "SEEN",
"sortDirection": "ASC",
"filters": [
{
"filterField": "TYPE",
"value": "THINGSTREAM_SIM"
}
],
"count": 50,
"offset": 0
}
Search for all SIM and INTERNET things sorting by Type Ascending
You may specify more than one value for type to get details of a range of device types as follows:
{
"sortField": "TYPE",
"sortDirection": "ASC",
"filters": [
{
"filterField": "TYPE",
"value": [
"THINGSTREAM_SIM",
"THINGSTREAM_INTERNET"
]
}
],
"count": 50,
"offset": 0
}
Search for Device by State
{
"sortField": "NAME",
"sortDirection": "ASC",
"filters": [
{
"filterField": "STATE",
"value": {}
}
],
"count": 50,
"offset": 0
}
When searching for a device by State we specify the filterField to be STATE. We have removed the "query" field as this is a general search.
State values are those listed as status on the Thing details tab of your Things. These may include
ALLOCATED, ACTIVE
Search for all Things in an ALLOCATED state sorting by name ascending.
{
"sortField": "NAME",
"sortDirection": "ASC",
"filters": [
{
"filterField": "STATE",
"value": ["ALLOCATED"]
}
],
"count": 50,
"offset": 0
}
Search for all ALLOCATED and ACTIVE things sorting by Type Ascending
You may specify more than one value for STATE to get details of a range of device types as follows:
{
"sortField": "TYPE",
"sortDirection": "ASC",
"filters": [
{
"filterField": "STATE",
"value": [
"ALLOCATED",
"ACTIVE"
]
}
],
"count": 50,
"offset": 0
}
Search for Device by Plan
{
"sortField": "NAME",
"sortDirection": "ASC",
"filters": [
{
"filterField": "PLAN",
"value": {}
}
],
"count": 50,
"offset": 0
}
When searching for a device by plan we specify the filterField to be PLAN. We have removed the "query" field as this is a general search.
Plan values will need to be specified as the identity of the tariff/plan. These values can be obtained by searching through all tarrifs/plans from the API endpoint /thing/tariffs or alternatively specifiyng the tariff/plan type e.g. thing/tariffs/THINGSTREAM_SIM
Search for all Things on a particular tariff/plan sorting by name ascending.
{
"sortField": "NAME",
"sortDirection": "ASC",
"filters": [
{
"filterField": "PLAN",
"value": ["tariff:b7xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"]
}
],
"count": 50,
"offset": 0
}
{
"sortField": "NAME",
"sortDirection": "ASC",
"filters": [
{
"filterField": "PLAN",
"value": ["plan:009xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"]
}
],
"count": 50,
"offset": 0
}
Search for all Things on one of multiple tariffs/plans sorting by name ascending.
{
"sortField": "NAME",
"sortDirection": "ASC",
"filters": [
{
"filterField": "STATE",
"value": [
"tariff:b7xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"plan:009xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
]
}
],
"count": 50,
"offset": 0
}
Search for Device by Type and State
{
"sortField": "NAME",
"sortDirection": "ASC",
"filters": [
{
"filterField": "TYPE",
"value": {}
},
{
"filterField": "STATE",
"value": {}
}
],
"count": 50,
"offset": 0
}
When searching for devices, we may combine one or more filter fields to narrow our search. In this example we specify one filterField to be TYPE and another filterField to be STATE. This enables us to search for all ACTIVE things of type THINGSTREAM_SIM for example. We have removed the "query" field as this is a general search.
Values for type and state are detailed in previous sections.
Search for all Things by type and state sorting by name ascending.
{
"sortField": "NAME",
"sortDirection": "ASC",
"filters": [
{
"filterField": "TYPE",
"value": ["THINGSTREAM_SIM"]
},
{
"filterField": "STATE",
"value": ["ACTIVE"]
}
],
"count": 50,
"offset": 0
}