These docs are for v1.0.1. Click to read the latest docs for v1.0.11.

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:

HeaderTypeDescriptionMandatory
Iotics-ClientRefStringApplies 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 scopesOptional
Iotics-ClientAppIdStringApplies to requests to provide a namespace for the application within which all the requests/responses are grouped irrespective of the clientRefMandatory
Iotics-TransactionRefStringUsed 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 charactersOptional
Iotics-ConsumerGroupStringConsumer group, for group listenerOptional

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:

ParameterTypeDescription
langStringLanguage code for labels and comments
scopeStringChoose from:

GLOBAL
LOCAL
LOCAL_OWN
AUTO
limitInt64Limits amount of results returned.

Default = 500
Maximum = 1000
offsetInt64Sets 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:

ParameterTypeDescription
expiryTimeoutDate-TimeUTC time for when the search request will expire
filterObjectUsed to filter your results
filter:locationObjectUse to filter by location
filter:location:locationObjectThe location being filtered by
filter:location:location:latDoubleThe latitude of the location being filtered by
filter:location:location:lonDoubleThe longitude of the location being filtered by
filter:location:location:radiusKmDoubleThe radius in km around the location to be filtered by
filter:propertiesArray of objectsUsed to filter Twin properties
filter:properties:keyStringFilter with the key (predicate) of the properties
filter:properties:key:langLiteralValueObjectUse a langLiteralValue to filter for a property
filter:properties:key:langLiteralValue:langStringThe 2- character language code for the property
filter:properties:key:langLiteralValue:valueStringThe value of the property you're filtering by
filter:properties:key:literalValueObjectUse a literalValue to filter by a property
filter:properties:key:literalValue:dataTypeStringXSD 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:valueStringString representation of the value according to XSD datatype specification
filter:properties:key:stringLiteralValueObjectUse a stringLiteralValue to filter by a property
filter:properties:key:stringLiteralValue:valueStringThe value of the property you're filtering by
filter:properties:key:uriValueObjectUse a URI to filter by a property
filter:properties:key:uriValue:valueStringThe value of the property you're filtering by
filter:textStringOne or more keywords which must match text from entity/point labels/comments

Note: Any, rather than all, of the keywords will produce a match
responseTypeStringChoose 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)