How can we help?
Categories:
OpenAPI
Thermostat API
ThermostatEvent Attributes
UPDATED
- 16 May 2025
The ThermostatEvent attributes allow you to schedule one-time events that override a thermostat’s standard recurring schedule. This interface enables adding, modifying, or deleting events, as well as retrieving existing pending events. Events added through the API are tracked as “External” events.
There are no restrictions on the number of events that can be added. Also, events cannot cross day boundaries. For events that need to cross day boundaries multiple events should be created.
When retrieving events with a get request, only current or pending events will be returned; historical events are not retrievable through the API.
Avoid Overlapping Events
Avoid adding overlapping events, as this may produce unexpected results.
Day Boundaries
Events cannot cross day boundaries. For events that need to span multiple days, create separate events for each day.
Origin
By default, GET requests will only show special events that were SET through the API. To see all events, set origin:All in your selection attributes.
The origin attribute indicates how the event was created:
- Internal: Created through the Pelican App.
- External: Created through the API.
- All: Applicable to both internal and external events.
The "editable" Attribute
The “editable” attribute can be set to Yes or No for an External event (default is “No”). When set to Yes, the event can be viewed and edited by users through the Pelican App. When set to No, the event can be viewed but not edited or deleted through the app.
ThermostatEvent - Object Attributes
Attribute names are not case-sensitive; attribute values are case-sensitive.
| Name | Values | Settable | Description |
|---|---|---|---|
| name | String | Yes | The configured name of the thermostat. |
| serialNo | String | No | The thermostat's serial number. |
| eventId | String | Yes | The unique ID of this event (See Note 1 below). |
| title | String | Yes | A descriptive label for the event. |
| startDate | String | Yes | The date of the event in ISO 8601 format. |
| startTime | String | Yes | The time of day ISO 8601 extended local time format. |
| endTime | String | Yes | The time of day ISO 8601 extended local time format. |
| system | Auto, Heat, Cool, Off | Yes | The thermostat's system mode during the event. |
| heatSetting | Integer | Yes | The thermostat's heat setpoint during the event.. |
| coolSetting | Integer | Yes | The thermostat's cool setpoint during the event. |
| fan | Auto, On | Yes | The thermostat's fan setting during the event. |
| keypad | On, Off | Yes | Thermostat keypad during the event, active or locked. On = Unlocked, Off = Locked. |
| outsideVentilation | On, Off | Yes | Whether the thermostat is allowed to use Outside Ventilation |
| editable | Yes, No | Yes | Whether a users can the edit the event through the Pelican App's Schedule Dashboard. |
| origin | Internal, External, All | No | How the event was created (See Note 2 below) |
| delete | Yes | Yes | Delete the specified event entry. |
Note 1 (eventId)
The eventId is a unique identifier for the event. It can be system-generated or user-provided. When adding a new event, if this attribute is not provided, the system will generate a unique eventId and return its value in the reply. Existing events can be modified or deleted by including the eventId in the request. To delete an existing event, specify the eventId in the selection and set the delete attribute to Yes.
Note 2 (origin)
The origin attribute indicates how the event was created:
- Internal: Created through the Pelican App.
- External: Created through the API.
- All: Applicable to both internal and external events.
Code Examples
GET
Get upcoming events for a thermostat named Lobby
curl -L "https://your-site-name.officeclimatecontrol.net/api.cgi?username=USERNAME&password=PASSWORD&request=get&object=ThermostatEvent&selection=name:Lobby;origin:all&value=eventId;title;startTime;endTime"
#!/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(
'USERNAME', # username
'PASSWORD', # password
'your-site-name.officeclimatecontrol.net' # website
);
# Define the selection and attributes to retrieve
my $selection = {
'name' => 'Lobby',
'origin' => 'all'
};
my $attrlist = ['eventId', 'title', 'startTime', 'endTime'];
# Call getAttributes to retrieve the ThermostatEvent data
my $result = $cc->getAttributes('ThermostatEvent', $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://your-site-name.officeclimatecontrol.net/api.cgi?username=USERNAME&password=PASSWORD&request=get&object=ThermostatEvent&selection=name:Lobby;origin:all&value=eventId;title;startTime;endTime"
try:
response = requests.get(url, verify=True)
if response.status_code == 200:
print("Success:", response.text)
else:
print("Error: HTTP", response.status_code)
except requests.exceptions.SSLError as e:
print("SSL Error:", str(e))
except requests.exceptions.RequestException as e:
print("Request Error:", str(e))
const https = require('https');
const url = 'https://your-site-name.officeclimatecontrol.net/api.cgi?username=USERNAME&password=PASSWORD&request=get&object=ThermostatEvent&selection=name:Lobby;origin:all&value=eventId;title;startTime;endTime';
https.get(url, (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
<result>
<ThermostatEvent>
<title>Test</title>
<startDate>2025-05-16</startDate>
<startTime>10:05</startTime>
<endTime>19:00</endTime>
<system>Auto</system>
<heatSetting>68</heatSetting>
<coolSetting>72</coolSetting>
<fan>Auto</fan>
<keypad>Off</keypad>
<origin>Internal</origin>
<eventId>EVENT-9267-2</eventId>
...
</ThermostatEvent>
<success>1</success>
<message>Retrieved attributes for 3 events.</message>
...
</result>
SET
Set a special event for the thermostat named "Lobby"
curl -L "https://your-site-name.officeclimatecontrol.net/api.cgi?username=USERNAME&password=PASSWORD&request=get&object=ThermostatEvent&selection=name:Lobby;&value=title:Test;startDate:2025-05-16;startTime:10:05;endTime:19:00;system:Auto;heatSetting:68;coolSetting:72;fan:Auto;keypad:Off;eventId:TestEvent;editable:Yes"
#!/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(
'USERNAME', # username
'PASSWORD', # password
'your-site-name.officeclimatecontrol.net' # website
);
# Define the selection and attributes to retrieve
my $selection = { 'name' => 'Lobby' };
my $attrlist = ['title', 'startDate', 'startTime', 'endTime', 'system', 'heatSetting', 'coolSetting', 'fan', 'keypad', 'eventId', 'editable'];
# Call getAttributes to retrieve the ThermostatEvent data
my $result = $cc->getAttributes('ThermostatEvent', $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://your-site-name.officeclimatecontrol.net/api.cgi?username=USERNAME&password=PASSWORD&request=get&object=ThermostatEvent&selection=name:Lobby;&value=title:Test;startDate:2025-05-16;startTime:10:05;endTime:19:00;system:Auto;heatSetting:68;coolSetting:72;fan:Auto;keypad:Off;eventId:TestEvent;editable:Yes"
try:
response = requests.get(url, verify=True)
if response.status_code == 200:
print("Success:", response.text)
else:
print("Error: HTTP", response.status_code)
except requests.exceptions.SSLError as e:
print("SSL Error:", str(e))
except requests.exceptions.RequestException as e:
print("Request Error:", str(e))
const https = require('https');
const url = 'https://your-site-name.officeclimatecontrol.net/api.cgi?username=USERNAME&password=PASSWORD&request=get&object=ThermostatEvent&selection=name:Lobby;&value=title:Test;startDate:2025-05-16;startTime:10:05;endTime:19:00;system:Auto;heatSetting:68;coolSetting:72;fan:Auto;keypad:Off;eventId:TestEvent;editable:Yes';
https.get(url, (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
<result>
<eventId>TestEvent</eventId>
<success>1</success>
<message>Updated 1 events.</message>
...
</result>