Categories:
OpenAPI
Thermostat API
Thermostat API Overview
UPDATED
The Pelican OpenAPI provides a comprehensive set of thermostat-related API categories, allowing developers to retrieve and modify configurations, monitor active statuses, manage schedules, and access historical data. These APIs support interactions with individual thermostats, all thermostats at a site, or specific subsets based on defined attributes.
Thermostat API Categories
Manage and retrieve real-time thermostat configurations and active settings.
Key Features:
- Control system modes (Auto, Heat, Cool, Off)
- Adjust setpoints for heating, cooling, humidity, and CO₂
- Lock/unlock the front keypad
- Retrieve fan and auxiliary heating statuses
ThermostatSchedule Attributes
Set and retrieve individual recurring schedules for thermostats.
Key Details:
- Allows custom schedules per thermostat
- Attribute names are not case-sensitive, while attribute values are case-sensitive
SharedSchedule Attributes
Create and manage shareable schedules for multiple thermostats.
Key Details:
- Shared schedules ensure consistent programming across multiple devices
- Attribute names are not case-sensitive, while attribute values are case-sensitive
ThermostatHistory Attributes
Retrieve historical thermostat readings and setpoint data.
Key Details:
- Required selection attributes:
startDateTimeandendDateTime(ISO 8601 format)
- Available data:
- System mode, setpoints, occupancy status, temperature, humidity, CO₂ levels, and run status
- Maximum 30 days of history per request
ThermostatEvent Attributes
Schedule one-time events that override a thermostat’s recurring schedule.
Key Details:
- Events do not cross day boundaries (create separate events per day)
- Avoid overlapping events to prevent conflicts
- The
editableattribute controls whether users can modify events in the Pelican App - Events created via API are labeled as “External”
ThermostatUsage Attributes
Retrieve run-time and consumption-related historical information.
Key Details:
- Required attributes:
startDateTime,endDateTime, andduration
- Available data:
- Heating and cooling runtime, fan usage, second-stage heating/cooling, kilowatt-hour consumption
- Data aggregation options:
month,day,15minuteintervals
- Maximum 30 days of history per request
Best Practices for Using the Thermostat API
Use Efficient Data Retrieval:
- Request only necessary attributes to optimize API performance.
- Retrieve thermostat data in batch queries instead of making multiple individual requests.
Create a Dedicated Developer User:
- Use a non-personal account for API integrations to ensure better user management.
Follow Standard Date Formats:
- Always use ISO 8601 timestamps (yyyy-mm-ddTHH:MM:SSZ).
Secure Your API Requests:
- Authenticate using username/password or token-based authentication via MySites.
Avoid Scheduling Conflicts:
- Do not create overlapping thermostat events.
- Ensure ThermostatEvent requests are structured properly to avoid unintended overrides.
By leveraging these six thermostat API categories and adhering to best practices, you can efficiently integrate, automate, and optimize Pelican thermostat functionalities within your applications.