How to search
On this page we'll cover how to search with the Iotics API's SearchService.
You can see the entire Iotics API Reference here.
Set your headers
The headers are an important part of your API request, representing the meta-data of your request. Before submitting a request you need to ensure you have set your headers:
Header | Type | Description | Mandatory |
---|---|---|---|
Iotics-ClientRef | String | Applies to all requests and solicited responses modelled as list to allow clients to represent the ref as a linked set of elements we will be using this to map to internal queues and provide namespace scopes | Optional |
Iotics-ClientAppId | String | Applies to requests to provide a namespace for the application within which all the requests/responses are grouped irrespective of the clientRef | Mandatory |
Iotics-TransactionRef | String | Used to loosely link requests/responses in a distributed environment each layer can add its own id to the list. Transaction ref is limited to a max of 16 elements per list and, for each list item, a max length of 36 characters | Optional |
Iotics-ConsumerGroup | String | Consumer group, for group listener | Optional |
The request
To search, you just submit a search POST
to the Iotics API's Search service.
You can see an example request here.
Query parameters
You first set the parameters of your query, deciding the scope of your search and how many results to return:
Parameter | Type | Description |
---|---|---|
lang | String | Language code for labels and comments |
scope | String | Choose from: GLOBAL LOCAL LOCAL_OWN AUTO |
limit | Int64 | Limits amount of results returned. Default = 500 Maximum = 1000 |
offset | Int64 | Sets where the results are returned from. Use with Limit to control what is returned. |
Body parameters
You then set the payload for your request, made up of:
Parameter | Type | Description |
---|---|---|
expiryTimeout | Date-Time | UTC time for when the search request will expire |
filter | Object | Used to filter your results |
filter:location | Object | Use to filter by location |
filter:location:location | Object | The location being filtered by |
filter:location:location:lat | Double | The latitude of the location being filtered by |
filter:location:location:lon | Double | The longitude of the location being filtered by |
filter:location:location:radiusKm | Double | The radius in km around the location to be filtered by |
filter:properties | Array of objects | Used to filter Twin properties |
filter:properties:key | String | Filter with the key (predicate) of the properties |
filter:properties:key:langLiteralValue | Object | Use a langLiteralValue to filter for a property |
filter:properties:key:langLiteralValue:lang | String | The 2- character language code for the property |
filter:properties:key:langLiteralValue:value | String | The value of the property you're filtering by |
filter:properties:key:literalValue | Object | Use a literalValue to filter by a property |
filter:properties:key:literalValue:dataType | String | XSD data type. Currently supports: dateTime, time, date, boolean, integer, nonPositiveInteger, negativeInteger, nonNegativeInteger, positiveInteger, long, unsignedLong, int, unsignedInt, short, unsignedShort, byte, unsignedByte, anyURI |
filter:properties:key:literalValue:value | String | String representation of the value according to XSD datatype specification |
filter:properties:key:stringLiteralValue | Object | Use a stringLiteralValue to filter by a property |
filter:properties:key:stringLiteralValue:value | String | The value of the property you're filtering by |
filter:properties:key:uriValue | Object | Use a URI to filter by a property |
filter:properties:key:uriValue:value | String | The value of the property you're filtering by |
filter:text | String | One or more keywords which must match text from entity/point labels/comments Note: Any, rather than all, of the keywords will produce a match |
responseType | String | Choose from: FULL LOCATED MINIMAL |
Examples
Example Search Request
This is an example of a POST
request to search for the first 750 results that have a property with a Key of "Key" and the langLiteralValue of "Example Property Value" in English.
curl --request POST \
--url 'https:///qapi/searches?lang=en&scope=GLOBAL&limit=750' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Iotics-ClientAppId: ExampleAppID' \
--header 'Iotics-ClientRef: ExampleRef' \
--data '{"filter":{"properties":[{"langLiteralValue":{"lang":"en","value":"Example Property Value"},"literalValue":{},"stringLiteralValue":{},"uriValue":{},"key":"key"}]},"responseType":"FULL"}'
const fetch = require('node-fetch');
const url = 'https:///qapi/searches';
const options = {
method: 'POST',
qs: {lang: 'en', scope: 'GLOBAL', limit: '750'},
headers: {
Accept: 'application/json',
'Iotics-ClientRef': 'ExampleRef',
'Iotics-ClientAppId': 'ExampleAppID',
'Content-Type': 'application/json'
},
body: JSON.stringify({
filter: {
properties: [
{
langLiteralValue: {lang: 'en', value: 'Example Property Value'},
literalValue: {},
stringLiteralValue: {},
uriValue: {},
key: 'key'
}
]
},
responseType: 'FULL'
})
};
fetch(url, options)
.then(res => res.json())
.then(json => console.log(json))
.catch(err => console.error('error:' + err));
require 'uri'
require 'net/http'
require 'openssl'
url = URI("https:///qapi/searches?lang=en&scope=GLOBAL&limit=750")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Post.new(url)
request["Accept"] = 'application/json'
request["Iotics-ClientRef"] = 'ExampleRef'
request["Iotics-ClientAppId"] = 'ExampleAppID'
request["Content-Type"] = 'application/json'
request.body = "{\"filter\":{\"properties\":[{\"langLiteralValue\":{\"lang\":\"en\",\"value\":\"Example Property Value\"},\"literalValue\":{},\"stringLiteralValue\":{},\"uriValue\":{},\"key\":\"key\"}]},\"responseType\":\"FULL\"}"
response = http.request(request)
puts response.read_body
const options = {
method: 'POST',
headers: {
Accept: 'application/json',
'Iotics-ClientRef': 'ExampleRef',
'Iotics-ClientAppId': 'ExampleAppID',
'Content-Type': 'application/json'
},
body: '{"filter":{"properties":[{"langLiteralValue":{"lang":"en","value":"Example Property Value"},"literalValue":{},"stringLiteralValue":{},"uriValue":{},"key":"key"}]},"responseType":"FULL"}'
};
fetch('https:///qapi/searches?lang=en&scope=GLOBAL&limit=750', options)
.then(response => console.log(response))
.catch(err => console.error(err));
import requests
url = "https:///qapi/searches"
querystring = {"lang":"en","scope":"GLOBAL","limit":"750"}
payload = {
"filter": {"properties": [
{
"langLiteralValue": {
"lang": "en",
"value": "Example Property Value"
},
"literalValue": {},
"stringLiteralValue": {},
"uriValue": {},
"key": "key"
}
]},
"responseType": "FULL"
}
headers = {
"Accept": "application/json",
"Iotics-ClientRef": "ExampleRef",
"Iotics-ClientAppId": "ExampleAppID",
"Content-Type": "application/json"
}
response = requests.request("POST", url, json=payload, headers=headers, params=querystring)
print(response.text)
Updated about 3 years ago