Asset

Think of an asset as a digital representation of any real-world object, no matter how complex or simple. For example, a water bottle could be an asset, but also a camera sensor, a transmission line, or just a sensor. An Asset consists of a name, a description, and a set of attributes. Recall that we interested in objects that produce real-time data such as sensors? The way we define these real-time dynamic characteristics is by assigning attributes to Assets. For example, temperature could be an attribute of an Asset.

Types of Assets

Splight supports a wide range of asset types, each designed to meet specific needs and functionalities. The following are some of the key asset types available:

Bus
Line
Transformer
Generator
Segment
Grid
Inverter

Creating Assets

To create an asset, you need to provide the necessary parameters such as name, description, and type. The API allows you to create assets programmatically. You can use the following code snippets to create an asset using cURL and Python.

curl --request POST \
    --url https://api.splight.com/v3/engine/asset/assets/ \
    --header 'authorization: Splight <access_id> <secret_key>' \
    --header 'content-type: application/json' \
    --data '{
        "name": "<asset_name>",
        "kind": {
            "id": "<asset_type_id>",
            "name": "<asset_type_name>"
        }
    }'

import requests

ACCESS_ID = "<user_access_id>"  # Replace with your access ID
SECRET_KEY = "<user_secret_key>"  # Replace with your secret key

url = "https://api.splight.com/v3/engine/asset/assets/"

payload = {
    "name": "asset_name",
    "kind": {
        "id": "<asset_type_id>",
        "name": "<asset_type_name>"
    }
}
headers = {
    "authorization": f"Splight {ACCESS_ID} {SECRET_KEY}",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
print(response.status_code)  # Should return 201 for successful creation

The list of asset types and their corresponding IDs is shown in the table above called Types of Assets.

The parameters shown in the example are required. The table below describes all the available parameters for creating an asset:

Field

Description

name

The name of the asset.

description

A brief description of the asset. Example: "" (empty string).

tags

A list of tags associated with the asset. Example: [] (empty array).

type

The type of the asset. Example: "Bus".

timezone

The timezone of the asset. Example: "UTC".

external_id

An external identifier for the asset. Example: null.

geometry

The geometry of the asset. Example: null.

centroid

The centroid of the asset. Example: null.

centroid_timezone

The timezone of the centroid. Example: "UTC".

use_custom_timezone

A boolean indicating whether a custom timezone is used. Example: false.

custom_timezone

The custom timezone of the asset. Example: "UTC".

Reading Assets

The Splight API provides a comprehensive set of endpoints for reading asset data. You can retrieve information about all assets or filter them based on specific criteria. The API supports various query parameters to help you narrow down your search. Let's explore some examples of how to read assets using the API. Below are simple code snippets using curl (with jq for JSON processing) and Python:

Listing all Assets

curl --request GET \
    --url https://api.splight.com/v3/engine/asset/assets/ \
    --header 'authorization: Splight <access_id> <secret_key>'

import requests

ACCESS_ID = "<user_access_id>"  # Replace with your access ID
SECRET_KEY = "<user_secret_key>"  # Replace with your secret key

url = f"https://api.splight.com/v3/engine/asset/assets/"
headers = {
    "authorization": f"Splight {ACCESS_ID} {SECRET_KEY}",
}

response = requests.get(url, headers=headers)
print(response.json())
print(response.status_code)  # Should return 200 for successful retrieval

Retrive a single Asset

For retrieving a single asset, you can use the asset ID in the URL.

curl --request GET \
    --url "https://api.splight.com/v3/engine/asset/assets/{asset_id}/"\
    --header 'authorization: Splight <access_id> <secret_key>'

import requests

ACCESS_ID = "<user_access_id>"  # Replace with your access ID
SECRET_KEY = "<user_secret_key>"  # Replace with your secret key
ASSET_ID = "<asset_id>"  

url = f"https://api.splight.com/v3/engine/asset/assets/{ASSET_ID}"
headers = {'authorization': f"Splight {ACCESS_ID} {SECRET_KEY}"}

response = requests.get(url, headers=headers)
print(response.json()) 
print(response.status_code)  # Should return 200 for successful retrieval

Updating Assets

To update an asset, you can use the PUT method with the asset ID in the URL. You need to provide the updated parameters in the request body.

curl --request PATCH \
    --url https://api.splight.com/v3/engine/asset/assets/{asset_id} \
    --header 'authorization: Splight <access_id> <secret_key>' \
    --header 'content-type: application/json' \
    --data '{
        {data_to_update}
    }'

import requests

ACCESS_ID = "<user_access_id>"  # Replace with your access ID
SECRET_KEY = "<user_secret_key>"  # Replace with your secret key
ASSET_ID = "<asset_id>"  # Replace with the asset ID

url = f"https://api.splight.com/v3/engine/asset/assets/{ASSET_ID}/"

payload = {
    "<data_to_update>"
}
headers = {
    "authorization": f"Splight {ACCESS_ID} {SECRET_KEY}",
    "content-type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.json())
print(response.status_code)  # Should return 200 for successful update

Where data_to_update refers to the fields you want to modify in the asset. These parameters are the same as those used when creating an asset. Refer to the table above for the full list.

Deleting Assets

To delete an asset, you can use the DELETE method with the asset ID in the URL.

curl --request DELETE \
    --url https://api.splight.com/v3/engine/asset/assets/{asset_id}/ \
    --header 'authorization: Splight <access_id> <secret_key>'

import requests
ACCESS_ID = "<user_access_id>"  # Replace with your access ID
SECRET_KEY = "<user_secret_key>"  # Replace with your secret key
ASSET_ID = "<asset_id>"  # Replace with the asset ID you want to delete

url = f"https://api.splight.com/v3/engine/asset/assets/{ASSET_ID}/"

headers = {
    "authorization": f"Splight {ACCESS_ID} {SECRET_KEY}",
    "content-type": "application/json"
}

response = requests.delete(url, headers=headers)

print(response.status_code)  # Should return 204 for successful deletion

Attributes

Attributes are the dynamic characteristics of an asset. They can be used to represent real-time data such as temperature, wind, current, etc. Attributes are associated with assets and can be updated or retrieved using the API.

Creating Attributes

To create an attribute, you need to provide the necessary parameters such as name, asset_id, type and unit in case that the attribute is a measurement. The API allows you to create attributes programmatically. You can use the following code snippets to create an attribute using cURL and Python.

curl --request POST \
    --url https://api.splight.com/v3/engine/asset/attributes/ \
    --header 'authorization: Splight <access_id> <secret_key>' \
    --header 'content-type: application/json' \
    --data '{
        "name": "<attribute_name>",
        "asset": "<asset_id>",
        "type": "<attribute_type>",
        "unit": "<attribute_unit>",
    }'

import requests
ACCESS_ID = "<user_access_id>"  # Replace with your access ID
SECRET_KEY = "<user_secret_key>"  # Replace with your secret key
ASSET_ID = "<asset_id>"  # Replace with the asset ID

url = "https://api.splight.com/v3/engine/asset/attributes/"

payload = {
    "name": "attribute_name",
    "asset": ASSET_ID,
    "type": "<attribute_type>",
    "unit": "<attribute_unit>",
}

headers = {
    "authorization": f"Splight {ACCESS_ID} {SECRET_KEY}",
    "content-type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)

print(response.json())
print(response.status_code)  # Should return 201 for successful creation

Where attribute_type refers to the type of the attribute. The available types are:

Boolean
Number
String

Reading Attributes

To read attributes, you can use the GET method with the asset ID in the URL or filter them based on specific criteria. The API supports various query parameters to help you narrow down your search.

Listing All Attributes

To list all attributes, you can use the following code snippets:

curl --request GET \
  --url 'https://api.splight.com/v3/engine/asset/attributes/?asset={asset_id}' \
  --header 'authorization: Splight <access_id> <secret_key>'

import requests

ACCESS_ID = "<user_access_id>"  # Replace with your access ID
SECRET_KEY = "<user_secret_key>"  # Replace with your secret key
ASSET_ID = "<asset_id>"  # Replace with the asset ID

url = f"https://api.splight.com/v3/engine/asset/attributes/?asset={ASSET_ID}"

headers = {
    "authorization": f"Splight {ACCESS_ID} {SECRET_KEY}",
    "content-type": "application/json"
}

response = requests.get(url, headers=headers)

print(response.json())
print(response.status_code)  # Should return 200 for successful retrieval

Where asset_id refers to the ID of the asset whose attributes you want to retrieve.

Retrieving a Single Attribute

To retrieve a single attribute, you can use the attribute ID in the URL.

curl --request GET \
    --url "https://api.splight.com/v3/engine/asset/attributes/{attribute_id}/" \
    --header 'authorization: Splight <access_id> <secret_key>'

import requests

ACCESS_ID = "<user_access_id>"  # Replace with your access ID
SECRET_KEY = "<user_secret_key>"  # Replace with your secret key
ATTRIBUTE_ID = "<attribute_id>"  # Replace with the attribute ID

url = f"https://api.splight.com/v3/engine/asset/attributes/{ATTRIBUTE_ID}/"

headers = {
    "authorization": f"Splight {ACCESS_ID} {SECRET_KEY}",
    "content-type": "application/json"
}

response = requests.get(url, headers=headers)

print(response.json())
print(response.status_code)  # Should return 200 for successful retrieval

Where attribute_id refers to the ID of the attribute you want to retrieve.

Reading Telemetry

The attribute values correspond to the device's telemetry, which can be ingested directly or calculated by a Splight algorithm. The telemetry data can be accessed through the API, allowing you to monitor and analyze the performance of your assets in real-time. To read telemetry data, you can use the following code snippets:

curl --request POST \
    --url "https://api.splight.com/data/read" \
    --header "Authorization: Splight <ACCESS_ID> <SECRET_KEY>" \
    --header "Content-Type: application/json" \
    --data '{
        "from_timestamp": "<FROM_TIMESTAMP>",
        "to_timestamp": "<TO_TIMESTAMP>",
        "collection": "default",
        "sort_direction": 1,
        "traces": [
            {
                "ref_id": "value",
                "type": "QUERY",
                "pipeline": [
                    {
                        "$match": {
                            "asset": "<ASSET_ID>",
                            "attribute": "<ATTRIBUTE_ID>"
                        }
                    },
                    {
                        "$addFields": {
                            "timestamp": {
                                "$dateTrunc": {
                                    "date": "$timestamp",
                                    "unit": "minute",
                                    "binSize": 5
                                }
                            }
                        }
                    },
                    {
                        "$group": {
                            "_id": "$timestamp",
                            "value": { "$avg": "$value" },
                            "timestamp": { "$last": "$timestamp" }
                        }
                    }
                ]
            }
        ]
    }'

The parameters to replace are:

Parameter

Description

Example Format

<ACCESS_ID>

Access credential (ID).

"abc123"

<SECRET_KEY>

Secret key.

"xyz789"

<ASSET_ID>

ID of the asset (device).

"line-001"

<ATTRIBUTE_ID>

ID of the attribute (measurement).

"active_power"

<FROM_TIMESTAMP>

Start date in ISO 8601 format (UTC).

"2024-03-01T00:00:00+0000"

<TO_TIMESTAMP>

End date in ISO 8601 format (UTC).

"2024-03-02T00:00:00+0000"

Timestamp Format: ISO 8601: "YYYY-MM-DDThh:mm:ss+0000" (e.g., "2024-05-08T14:30:00+0000").
Data Aggregation: The query uses $dateTrunc to group data in 5-minute intervals and $avg to compute average values.
Warning: Very large time ranges may lead to slow responses or timeouts.

Updating Attributes

To update an attribute, you can use the PATCH method with the attribute ID in the URL. You need to provide the updated parameters in the request body.

curl --request PATCH \
    --url https://api.splight.com/v3/engine/asset/attributes/{attribute_id}/ \
    --header 'authorization: Splight <access_id> <secret_key>' \
    --header 'content-type: application/json' \
    --data '{
        <data_to_update>
    }'

import requests
ACCESS_ID = "<user_access_id>"  # Replace with your access ID
SECRET_KEY = "<user_secret_key>"  # Replace with your secret key
ATTRIBUTE_ID = "<attribute_id>"  # Replace with the attribute ID

url = f"https://api.splight.com/v3/engine/asset/attributes/{ATTRIBUTE_ID}/"

payload = {
    "<data_to_update>"
}

headers = {
    "authorization": f"Splight {ACCESS_ID} {SECRET_KEY}",
    "content-type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.json())
print(response.status_code)  # Should return 200 for successful update

Where data_to_update refers to the fields you want to modify in the attribute. These parameters are the same as those used when creating an attribute, except for attribute_type which cannot be modified.

Deleting Attributes

To delete an attribute, you can use the DELETE method with the attribute ID in the URL.

curl --request DELETE \
    --url https://api.splight.com/v3/engine/asset/attributes/{attribute_id}/ \
    --header 'authorization: Splight <access_id> <secret_key>'

import requests

ACCESS_ID = "<user_access_id>"  # Replace with your access ID
SECRET_KEY = "<user_secret_key>"  # Replace with your secret key
ATTRIBUTE_ID = "<attribute_id>"  # Replace with the attribute ID

url = f"https://api.splight.com/v3/engine/asset/attributes/{ATTRIBUTE_ID}/"

headers = {
    "authorization": f"Splight {ACCESS_ID} {SECRET_KEY}",
    "content-type": "application/json"
}

response = requests.delete(url, headers=headers)
print(response.status_code)  # Should return 204 for successful deletion

Where attribute_id refers to the ID of the attribute you want to delete.

Metadata

Metadata is additional information associated with an asset.

Creating and Updating Metadata

Metadata cannot be created directly via a GET request. Instead, you must use a PATCH request on the asset to add or update metadata. To create or update metadata, you can use the PATCH method with the asset ID in the URL. You need to provide the updated parameters in the request body.

curl --request PATCH \
    --url https://api.splight.com/v3/engine/asset/assets/{asset_id}/ \
    --header 'authorization: Splight <access_id> <secret_key>' \
    --header 'content-type: application/json' \
    --data '{
        "metadata": {
            "key1": "<value1>",
            "key2": "<value2>"
        }
    }'

import requests

ACCESS_ID = "<user_access_id>"  # Replace with your access ID
SECRET_KEY = "<user_secret_key>"  # Replace with your secret key
ASSET_ID = "<asset_id>"  # Replace with the asset ID
url = f"https://api.splight.com/v3/engine/asset/assets/{ASSET_ID}/"

payload = {
    "metadata": {
        "key1": "<value1>",
        "key2": "<value2>"
    }
}

headers = {
    "authorization": f"Splight {ACCESS_ID} {SECRET_KEY}",
    "content-type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)
print(response.json())
print(response.status_code)  # Should return 200 for successful update

Where asset_id refers to the ID of the asset whose metadata you want to create or update.

Deleting Metadata

To delete metadata, you can use the DELETE method witch the metadata ID in the URL.

curl --request DELETE \
    --url https://api.splight.com/v3/engine/asset/metadata/{metadata_id}/ \
    --header 'authorization: Splight <access_id> <secret_key>'

import requests 

ACCESS_ID = "<user_access_id>"  # Replace with your access ID
SECRET_KEY = "<user_secret_key>"  # Replace with your secret key
METADATA_ID = "<metadata_id>"  # Replace with the metadata ID

url = f"https://api.splight.com/v3/engine/asset/metadata/{METADATA_ID}/"
headers = {
    "authorization": f"Splight {ACCESS_ID} {SECRET_KEY}",
    "content-type": "application/json"
}

response = requests.delete(url, headers=headers)
print(response.status_code)  # Should return 204 for successful deletion

Where metadata_id refers to the ID of the metadata you want to delete.

PreviousAlert NextComponent

Last updated 2 months ago

Was this helpful?