Assets

What is an Asset?

In Splight, an Asset represents a specific element of the power grid—such as a transmission line, transformer, breaker, battery, or generator. Each Asset is modeled with two types of information:

• Metadata: Static properties that describe the grid element (e.g., voltage rating, location, equipment ID).

• Input Attributes: Real-time measurements or status signals collected from the field (e.g., current flow, breaker state, temperature).

These Input Attributes are automatically populated by Connectors, which stream data from physical devices into Splight. Assets are the foundation of Splight’s real-time grid model and are used throughout the platform for analytics, automation, and simulations.

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

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>"
        }
    }'

Python

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

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

Python

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

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

Python

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

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}
    }'

Python

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

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

Python

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

Input 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.

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

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

Python

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

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

Python

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

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>
    }'

Python

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.