How can we help?
Print

Categories:

OpenAPI

Thermostat API

ThermostatEvent Attributes

UPDATED

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. When retrieving events with a get request, only current or pending events will be returned; historical events are not retrievable through the API.

Predefined system-managed attributes for ThermostatEvent 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 ThermostatEvent 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.

User-defined attributes can also be used as selection criteria. For example, if a user wants to manage a specific group of thermostats via the API, they could define an attribute named “managed” and SET its value to “yes” for the thermostats in that group. Then, by including “managed:yes;” in their selection criteria, they can filter and control only those thermostats within the designated group.

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.

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 the current Temperature, Humidity, and CO2 Level for a thermostat named "Lobby"

				
					curl -Ls "https://demo.officeclimatecontrol.net/api.cgi?username=pelicandemosite@gmail.com&password=pelican&request=get&object=Thermostat&selection=name:Lobby;&value=temperature;humidity;co2Level"
				
			
				
					#!/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 = { 'name' => 'Lobby' };
my $attrlist = ['temperature', 'humidity', 'co2Level'];

# Call getAttributes to retrieve the Thermostat data
my $result = $cc->getAttributes('Thermostat', $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=Thermostat&selection=name:Lobby;&value=temperature;humidity;co2Level"
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=Thermostat&selection=name:Lobby;&value=temperature;humidity;co2Level';

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

				
					<result>
<Thermostat>
<temperature>71.5</temperature>
<humidity>40</humidity>
<co2Level>1049</co2Level>
...
</Thermostat>
<success>1</success>
<message>Retrieved attributes for 1 thermostats.</message>
...
</result>
				
			

SET

Set the Heating and Cooling Ranges for the thermostat named "Lobby"

				
					curl -Ls "https://demo.officeclimatecontrol.net/api.cgi?username=pelicandemosite@gmail.com&password=pelican&request=set&object=Thermostat&selection=name:Lobby;&value=heatMin:50;heatMax:68;coolMin:72;coolMax:85"
				
			
				
					#!/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 values as hashes
my $selection = { 'name' => 'Lobby' };
my $values = {
    'heatMin' => '50',
    'heatMax' => '68',
    'coolMin' => '72',
    'coolMax' => '85'
};

# Call setAttributes to update the Thermostat
my $result = $cc->setAttributes('Thermostat', $selection, $values);

# 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=set&object=Thermostat&selection=name:Lobby;&value=heatMin:50;heatMax:68;coolMin:72;coolMax:85"
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=set&object=Thermostat&selection=name:Lobby;&value=heatMin:50;heatMax:68;coolMin:72;coolMax:85';

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

				
					<result>
<success>1</success>
<message>Updated 1 thermostats.</message>
...
</result>
				
			
Table of Contents