Search for Twins

Find your own and others' Digital Twins by using both Search and Advanced Search functions.

This page covers:

You can find your own and others’ Digital Twins using the Search and Advanced Search functions. Although you can use the same search criteria, they have important differences - please see our Comparison Table for details.

Comparison Table - Search vs Advanced Search

SearchAdvanced Search
Match properties using equals.
i.e: Battery voltage = 5V
Compare properties.
i.e: Battery voltage = or >5V
Match Twin properties
i.e: Twin Label = ‘Engine’
Match against Twins, Feeds and Inputs
i.e: Twin Label OR Feed Label OR
Input Label = ‘Engine’
All properties should match
i.e: Twins near Manchester AND Twin colour = blue
You decide which properties should match and
if they should match.
AND/OR groups can be nested.
i.e: Twins near Manchester OR Twin colour = blue
Single location search
i.e: Twins in Manchester
Multiple locations can be searched for
simultaneously
i.e.: Twins near Manchester and Cardiff
Flexible text search.
Enter general terms to find, for example,
weather stations in London.
i.e: Weather London
Exact text search.
Enter what you are looking for specifically,
i.e.: Weather Forecast London.
REST, STOMP and gRPCgPRC
Max. (default) limit for pagination is 100 results.Max. (default) limit for pagination is
1000 results.

Search for Twins

Use the Search Twin call to find your and others' Digital Twins in your IOTICS ecosystem. You can select and combine one or more search criteria, including:

  • Property: define a list of Twins properties, such as Type, Label, Comment, Last Update, etc. Properties can be matched using equals.
  • Location: define Latitude, Longitude and Radius expressed in Km. You can search for one location at a time.
  • Text: define one or more keywords that must match text fields from Twin’s Label and Comment.
  • Scope (ownership): distinguish between finding only your own local Digital Twins, vs all global Digital Twins.

Using the Search function

Click here to see the prerequisites.

import json
from datetime import datetime, timedelta, timezone
from requests import request

# Search headers require a new header "Iotics-RequestTimeout".
# The latter is used to stop the request once the timeout is reached
search_headers = {
    "accept": "application/json",
    "Iotics-ClientAppId": "example_code",
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json",
    "Iotics-RequestTimeout": (
        datetime.now(tz=timezone.utc) + timedelta(seconds=5)
    ).isoformat(),
}

# The variable below will include the list of Twins found
twins_list = []

with request(
    method="POST",
    url=f"{HOST}/qapi/searches",
    headers=search_headers,
    stream=True,
    verify=True,
    params={"scope": "LOCAL"},
    json={
        "responseType": "FULL",
        "filter": {
            "properties": [
                {
                    "key": "http://www.w3.org/1999/02/22-rdf-syntax-ns#type",
                    "uriValue": {"value": "http://data.iotics.com/app#Model"},
                }
            ],
            "text": "temperature",
            "location": {
                "location": {"lon": 52.2, "lat": 0.119},
                "radiusKm": 3.2,
            },
        },
    },
) as resp:
    resp.raise_for_status()
    # Iterates over the response data, one Host at a time
    for chunk in resp.iter_lines():
        response = json.loads(chunk)
        twins_found = []
        try:
            twins_found = response["result"]["payload"]["twins"]
        except KeyError:
            continue
        finally:
            if twins_found:
                # Append the twins found to the list of twins
                twins_list.extend(twins_found)

print(f"Found {len(twins_list)} twin(s)")

Advanced Search for Twins

Use the Advanced Search Twin call to find your and others' Digital Twins in your IOTICS ecosystem. You can select and combine one or more search criteria, including:

  • Property: define a list of Twins’, Feeds’ and Inputs’ properties, such as Type, Color, and Last Update. Properties can be combined using operators (i.e. ">", "<=", "!", etc.)
  • Location: define Latitude, Longitude and Radius expressed in Km. You can search for multiple locations simultaneously.
  • Text: exact match of any text-value property on a Twin, Feed or Input.
  • Scope (ownership): distinguish between finding only your own local Digital Twins, vs all global Digital Twins.

Using the Advanced Search function

Click here to see the prerequisites.

Let's find the Twins which:

  • Have been created before 10/02/2022 AND
  • Don’t have myOnto:someProp with value 20 (but do have it set!) OR
  • Have a feed with myOnto:anotherProp set to False
{
  "prefixes": {
    "myOnto": "http://example.org/my/ontology/",
    "iotics": "http://data.iotics.com/iotics#"
  },
  "filter": {
    "and": [
      {"<": ["iotics:createdAt", {"strdt": ["2022-10-02", "xsd:date"]}]},
      {"or": [
        {"!=": ["myOnto:someProp", 20]},
        {"==": [["$feed", "myOnto:anotherProp"], false]}
      ]}
    ]
  }
}

🚧

Distinguish between your own local Digital Twins and others' remote Digital Twins

  • Local: returns all Digital Twins in your own IOTICSpace
  • Global: returns all Digital Twins in others' (remote) IOTICSpaces.

Please note that you will only find Digital Twins that you have permission to find. See Selective Sharing for Metadata and Data for more information on access permissions.

The following table provides an indication of the filters that can be used in the request parameters when searching for Twins.

KeyDescription
PropertiesSearch by any available Digital Twin property as described here.
LocationDefines a specific geo-location with radius.
TextSearch one or more keywords which must match the text from the Twin's properties.
ScopeDistinguish between Twins in your own local Host/IOTICSpace or all Twins in your global network.
LimitDefine the maximum number of Twins to return.
OffsetUsed to return results from a given offset.

An important feature of both searching functions is that it allows you to describe one or more Twins through the responseType body parameter. It can be set to:

  • MINIMAL: used to return minimal responses including a Twin's DID.
  • LOCATED: includes the MINIMAL fields in addition to the Twin's location;
  • FULL (default): provides a complete description of the Twin, including all metadata about the Twin, its Feeds, Inputs and the Feeds' and Inputs’ Values.