How can we help?
Requests
Encryption
All requests must be sent using HTTPS. Transactions are only allowed over Secure Socket Layer (SSL) connections using password protection. Since the Pelican system only allows SSL connections, the password is automatically encrypted for each request.
Request
All Pelican API request must include the following six (6) elements in each request:
| Value | Description |
|---|---|
| username | This is the Email ID of a valid Pelican Site Manager user. This Email ID is created using the administrative interface of the Pelican Web App. |
| password | This is the password for the Email ID specified above. Since the Pelican system only allows SSL connections, the password is automatically encrypted for each request. |
| request | The value of this parameter should be either “set” or “get”. This identifies the type of request being made. “get” requests are intended to provide the current values of attributes being requested. “set” requests are intended to change the values of attributes. |
| object |
This is the type of object to which the “get” or “set” is being applied. The currently supported object
types are: 1. For Thermostats: Thermostat, ThermostatSchedule, SharedSchedule, ThermostatHistory, ThermostatEvent, and ThermostatUsage. 2. For Power Control Modules: PowerOutput and PowerSchedule. 3. For MySites: Sites. 4. For User Management: User. 5. For Notifications: Notification. 6. For Demand Response: Site and DemandResponseHistory. 7. For PowerLink: PowerUsage. |
| selection | This is a set of attribute/value pairs which should be used as a query match for the “set” or “get” request. In a “get” request, items matching the selection will be returned in the XML reply. In a “set” request, items matching the selection will be modified in the Pelican system. Pairs are separated by semicolons (;) and attributes are separated from their values by colons (:) (See example below). Attribute names are not case sensitive. Attribute values are case sensitive. |
| value | For “get” requests, this is a semicolon (;) separated list of attributes which are being requested. For a “set” request, this is a semicolon (;) separated list of attribute/value pairs to be modified. The attribute names are separated from their values by a colon (:). Semicolons and colons are invalid characters for either the attribute or the value. Attribute names are not case sensitive. Attribute values are case sensitive. |
When using HTTP GET, the 6 required elements must be formatted using standard HTTP notation with the element name as shown below followed by an equal sign and then that elements value. The first element is preceded by a question mark (?) and the elements are separated by the ampersand (&) character. Standard HTTP character escaping is supported. When using HTTP POST, standard encoding is supported.
Results
The default response formatting is XML. The results include a status and message attribute indicating the success or failure of the request and a table of objects matching the requested object. If the success attribute equals "1" the request was good and at least one result was found. If the success attribute equals "0" then either the request failed or no results were returned. Use the content of the message attribute to determine why a request failed.
To receive results in JSON format add an additional header to your API request of: Accept: application/json
Object Attributes
There are currently 14 object directories supported by the Pelican API.
Attribute names are not case sensitive. Attribute values are case sensitive.
Sample Request
The web address of the API interface is the full web address of the site followed by “/api.cgi”. Therefore, a valid API request would be as follows:
https://demo.officeclimatecontrol.net/api.cgi?username=myname@gmail.com&password=mypassword&request=get&object=Thermostat&selection=name:TestThermostat;&value=heatSetting;coolSetting;temperature;