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
  • how to find your and others' Digital Twins
• Introduction to Describe Twins
  • how to inspect a Digital Twins' metadata
• Introduction to List All Twins
  • how to list and describe all Digital Twins in a specific IOTICSpace

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.

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

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.

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

from requests import request

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

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