Search & Describe Twins

Find your own and others' Digital Twins by using the Search Twin function. Understand and inspect their data by using Describe or List All Twins.

This page covers:


Introduction to Search 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 properties, such as Type, Color, Last Update, etc.;
  • Location: define Latitude, Longitude and a Radius expressed in Km;
  • Text: define one or more keywords that must match text fields from Twin properties.
  • Scope (ownership): distinguish between finding only your own local Digital Twins, vs all global Digital Twins

🚧

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 your own and 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. Note that any (rather than all) of the keywords will produce a match.
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 the Search function is that it allows to search and describe one or more Twins with one single call through the responseType body parameter. It can be set to:

  • MINIMAL: used to return minimal responses including a Twin's DID and visibility setting;
  • 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 and the Feeds' Values.

How to search for Twins with the IOTICS API

Click to see the prerequisites

  1. Create your user credentials (guide);
  2. Delegate the agent so it can work on behalf of the user (guide);
  3. Create your token to interact with your Host (guide);
  4. Create headers to be added alongside the API request (guide);
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)")

Introduction to Describe Twins

Use Describe Twin to inspect a Digital Twin's metadata and find out more about it. It returns information about the Twin itself, its Feeds and each of the Feeds' Values in order to allow you to distinguish one Twin from another.

🚧

A prerequisite for Describe Twin is the Twin's DID

You may know it already or have to retrieve it by using Search Twin.

How to describe a Twin with the IOTICS API

🚧

Local vs Remote

The Describe Twin API is used differently depending on whether the Twin is in your own local IOTICSpace or in another remote IOTICSpace.

Click to see the prerequisites

  1. Create your user credentials (guide);
  2. Delegate the agent so it can work on behalf of the user (guide);
  3. Create your token to interact with your Host (guide);
  4. Create headers to be added alongside the API request (guide);
from requests import request

response = request(
    method="GET",
    url=f"{HOST}/qapi/hosts/{host_id}/twins/{twin_did}",
    headers=headers,
)

response.raise_for_status()
print(response.json())

Introduction to List All Twins

List All Twins allows you to list and describe all Digital Twins of a specific IOTICSpace.

🚧

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

How to list all Twins with the IOTICS API

Click to see the prerequisites

  1. Create your user credentials (guide);
  2. Delegate the agent so it can work on behalf of the user (guide);
  3. Create your token to interact with your Host (guide);
  4. Create headers to be added alongside the API request (guide);
from requests import request

response = request(
    method="GET",
    url=f"{HOST}/qapi/twins",
    headers=headers,
)

response.raise_for_status()
print(response.json())