Categories:
OpenAPI
PowerLink API
PowerUsage Attributes
UPDATED
The PowerUsage attributes allow you to obtain summarized energy usage data tracked by a Pelican PowerLink.
Note: The PowerLink is a special order item primarily used by utilities or utility program managers to monitor energy consumption at meters or dedicated equipment at Pelican customer sites. If your company is interested in a PowerLink, please contact Pelican’s Sales team.
Predefined system-managed attributes for PowerUsage objects, used for essential functions like temperature control, system status, and scheduling. They follow a fixed structure and cannot be renamed or redefined by users.
Reserved Attributes
User Defined Attributes
Custom attributes that users can create, set, and retrieve for PowerUsage objects. Any attribute name that is not reserved is treated as user-defined. These attributes are created by assigning a value via a SET request and can be accessed using GET requests. There is no restriction on the number of user-defined attributes, allowing flexibility for custom data storage and retrieval.
PowerUsage Request Requirements
A PowerUsage request must include at least the following required selection attributes:
- startDateTime – The beginning of the historical data range.
- endDateTime – The end of the historical data range.
- duration – Defines how the data should be aggregated (e.g., by month, day, or 15-minute intervals).
If no specific PowerUsage object attributes are included in the request, all available PowerUsage data within the specified date range will be returned.
PowerUsage - Selection Attributes
Attribute names are not case-sensitive; attribute values are case-sensitive.
| Name | Values | Required | Description |
|---|---|---|---|
| startDateTime | Date/Time | Yes | ISO 8601 formatted date and time indicating the start of the data range. |
| endDateTime | Date/Time | Yes | ISO 8601 formatted date and time indicating the end of the data range. |
| duration | One of: month, day, isoDuration | Yes |
Results are summarized into time intervals which match the specified duration.
- Month: results are for the entire month. A maximum of 12 months of usage can be retrieved in a single request. - Day: results are for each day. A maximum of 31 days of usage can be retrieved in a single request. -isoDuration: ISO 8601 Formatted Duration, results are for the specified intervals (ie. 15 minute intervals = PT15M, 1 hour intervals = PT1H). |
| name | String | No | The configured name of the PowerLink input. |
| groupName | String | No | The configured group name of the PowerLink input. |
| serialNo | String | No | The PowerLink serial number. |
| meterId | String | No | The configured Meter ID of the PowerLink input. |
PowerUsage - Value Attributes
Attribute names are not case-sensitive; attribute values are case-sensitive.
| Name | Values | Description |
|---|---|---|
| name | String | The configured name of the PowerLink input. |
| groupName | String | The configured group name of the PowerLink input. |
| serialNo | String | The serial number of the PowerLink device. |
| meterId | String | The configured Meter ID of the PowerLink input. |
| kWh | Decimal | The calculated kilowatt-hours for the interval. |
| kW | Decimal | The calculated average kilowatt rate during the interval. |
| unitsPerPulse | Decimal | The PowerLink Pulse Multiplier (in WattHours) |
| units | String | The configured unit type for the PowerLink |
| timestamp | Date/Time | ISO 8601 Formatted Date Time. |
Cost Calculations
To obtain accurate cost estimates, ensure that the Cost per Kilowatt-hour (Kwh) is correctly configured in your Pelican system settings. These settings allow the system to convert energy usage into monetary values, providing insights into the operational costs of monitored equipment.
Usage Graphs
Code Examples
GET
Get daily energy consumption data (kWh, kW, and timestamps) for March 2025 from all PowerLink devices in the system
curl -Ls "https://demo.officeclimatecontrol.net/api.cgi?username=pelicandemosite@gmail.com&password=pelican&request=get&object=PowerUsage&selection=startDateTime:2025-03-01T00:00:00Z;endDateTime:2025-03-31T23:59:59Z;duration:day;&value=name;kWh;kW;timestamp"
#!/usr/bin/perl -w
use strict;
use ClimateControl;
# You can request a copy of the ClimateControl Perl
# Module from Pelican Tech Support.
# Send an email to support@pelicanwireless.com
# Create a new ClimateControl object
my $cc = ClimateControl->new(
'pelicandemosite@gmail.com', # username
'pelican', # password
'demo.officeclimatecontrol.net' # website
);
# Define the selection and attributes to retrieve
my $selection = {
'startDateTime' => '2025-03-01T00:00:00Z',
'endDateTime' => '2025-03-31T23:59:59Z',
'duration' => 'day'
};
my $attrlist = ['name', 'kWh', 'kW', 'timestamp'];
# Call getAttributes to retrieve the PowerUsage data
my $result = $cc->getAttributes('PowerUsage', $selection, $attrlist);
# Check and display the result
if ($result->{'success'}) {
print "Success: $result->{'message'}\n";
} else {
print "Error: $result->{'message'}\n";
}
import requests
url = "https://demo.officeclimatecontrol.net/api.cgi?username=pelicandemosite@gmail.com&password=pelican&request=get&object=PowerUsage&selection=startDateTime:2025-03-01T00:00:00Z;endDateTime:2025-03-31T23:59:59Z;duration:day;&value=name;kWh;kW;timestamp"
response = requests.get(url, verify=False)
if response.status_code == 200:
print("Success:", response.text)
else:
print("Error:", response.status_code)
const https = require('https');
const url = 'https://demo.officeclimatecontrol.net/api.cgi?username=pelicandemosite@gmail.com&password=pelican&request=get&object=PowerUsage&selection=startDateTime:2025-03-01T00:00:00Z;endDateTime:2025-03-31T23:59:59Z;duration:day;&value=name;kWh;kW;timestamp';
https.get(url, { rejectUnauthorized: false }, (resp) => {
let data = '';
// Collect data chunks
resp.on('data', (chunk) => {
data += chunk;
});
// Handle the complete response
resp.on('end', () => {
if (resp.statusCode === 200) {
console.log('Success:', data);
} else {
console.log('Error: HTTP', resp.statusCode);
}
});
}).on('error', (err) => {
console.error('Error:', err.message);
});
Response
<?xml version="1.0" encoding="UTF-8"?>
<result>
<PowerUsage>
<name>PowerLink-123456</name>
<Usage>
<kWh>11766.7350</kWh>
<kW>490.2806</kW>
<timestamp>2025-03-01T00:00:00Z</timestamp>
</Usage>
</PowerUsage>
<success>1</success>
<message>Retrieved attributes for 2 power devices.</message>
</result>