Using the OpenControl API

POST and GET records sent to and received from the different URLs are made up of key/value pairs that represent the various capabilities exposed through the API. This structure uses the JSON syntax. Example:

{key1: value1, key2: value2, … keyN, valueN}

POST records do not need to contain all key/value pairs and can contain any subset of key/values based on the needs of the integration. The order of a request record is not important, so long as the key/value pairs follow the format above. For example, POSTing the string ‘{key2:value2}’ to the appropriate URL of a Solstice Pod can set that value.

In some cases, key/value pairs are organized hierarchically based on logical groupings. In these cases, the JSON syntax is simply nested within the value of a particular key. Those key/value pairs appear within brackets and are separated from other key/value pairs with a comma. Example:

{key1:value1, key2:value2, GroupKey:{ NestedKey1:GroupValue1, …, NestedKeyN:GroupValueN }, key3:value3}

This represents a JSON structure that contains three key/value pairs at the top level, and a set of key/value pairs that are grouped within ‘GroupKey’.

Using this syntax, for example, a user could set the display name for a particular Solstice Pod by sending the following JSON record:

{m_displayInformation:{m_displayName:‘NewDisplayName’}}

To ensure that only valid third-party users are able to communicate with Solstice Pods, the administration password, when set, must be provided with each POST or GET record. The administration password, for a particular Pod, can be set both in the Solstice Pod Configuration Panel, or through the Solstice Dashboard.

When an administrator password is set, each POST request record must include a key/value pair that is: ‘password: admin_password’ at the top level of the record. A request record sent to a Solstice Pod that has password enabled, then, must follow this format:

{password: admin_password, key1: value1, key2: value2, … keyN, valueN}

In the case of a GET record, the password is simply appended to the GET URL request as follows:

?password=admin_password

There are two URLs for each IP address that respond with text to a GET command. For our example IP address of 192.168.3.127, the valid URLs are:

While there is some overlap in information, the “stats” URL generally gives a snapshot of important values and instantaneous usage while the “config” URL gives more detail about everything from enabled options to appear screen layout. Note that while you can GET from either URL, you can only POST to /api/config.

To test the stats URL, set up your environment as described in the previous section and send the following command (with your own URL):

>>> rs=requests.get(‘http://192.168.3.127/api/stats’)

If you have an admin password protecting access to the display, append the password in the following way, with “adminpassword” as whatever the actual password is for the display.

>>> rs=requests.get(‘http://192.168.3.127/api/stats?password=adminpassword’)

To display the raw results, type:

>>> rs.text

You should see a continuous chunk of text with the first distinct value of “m_displayID”. To pull out a specific value in a clean format, the string needs to be converted to a dictionary of key:value pairs.

>>> rstats = eval(rs.text)

If you print the new value (rstats.text) you still see a chunk of continuous text, but the formatting is slightly different. We can now use get() to find specific terms, like the display name. m_displayName is a part of the m_displayInformation group key, so we use nested get() commands:

>>> print “Display Name:”, rstats.get(‘m_displayInformation’,{}).get(‘m_displayName’)

The result should be “Display Name: Pikes Peak” with the actual display name reflecting the name on your Solstice display. Any of the values can be pulled from the list in this manner.

Many of the key:value pairs that can be read using GET can also be changed through the API using POST. While the same values may appear in the GET of both URLs, POSTs may only be sent to the /api/config URL:

The requests command now changes from GET to POST and requires a payload parameter. To change the display name, use the following command:

>>> r=requests.post(‘http://192.168.3.207/api/config’, json={‘m_displayInformation’:{‘m_displayName’:’New Name’}})

If you have an admin password protecting the display, send the following command where ‘adminpassword’ is the actual password for the display:

>>> r=requests.post(‘http://192.168.3.207/api/config’, json={‘password’: ‘admin_password’, ‘m_displayInformation’:{‘m_displayName’:’New Name’}})

To see the new name, run GET on the same URL and look for the ‘m_displayName’ key, which should now have a value of ‘New Name’:

>>> rc=requests.get(‘http://192.168.3.127/api/config’)
>>> rconfig=eval(rc.text)
>>> print “Display Name:”, rconfig.get(‘m_displayInformation’,{}).get(‘m_displayName’)

If you have an admin password protecting the display, you need to add in the password as before.

The complete script provides additional comments and the option for an admin password. Download the complete script (https://github.com/LauraMersive/APIdemo/blob/master/OpenControlGETPOSTdemo.py).

This pared down version gets the Display Name from both /config and /stats URLs, changes the name, then gets both values again to confirm the name has changed.

import sys
import requests
import random
from random import choice
true=1
false=0

newname = “New Name”
myurl = “http://192.168.3.227”
admin_password = “”
mystatsurl = myurl+’/api/stats’
myconfigurl = myurl+’/api/config’

rs=requests.get(mystatsurl)
rc=requests.get(myconfigurl)
rstats=eval(rs.text)
rconfig=eval(rc.text)

print “Current Display Name from Stats:”,
rstats.get(‘m_displayInformation’,{}).get(‘m_displayName’)
print “Current Display Name from Config:”,
rconfig.get(‘m_displayInformation’,{}).get(‘m_displayName’)

r=requests.post(myconfigurl, json=
{‘password’:’admin_password’,’m_displayInformation’:
{‘m_displayName’:newname}})

print “Changing Name to: “,newname
print “………….”

rs=requests.get(mystatsurl)
rc=requests.get(myconfigurl)
rstats=eval(rs.text)
rconfig=eval(rc.text)

print “New Display Name from Stats:”,
rstats.get(‘m_displayInformation’,{}).get(‘m_displayName’)
print “New Display Name from Config:”,
rconfig.get(‘m_displayInformation’,{}).get(‘m_displayName’)

If you start writing your own script, you need to import the requests package before attempting to execute any GET/POST code. You also need to import sys, and likely want time as well. Though it seems redundant, you can avoid errors later on by explicitly defining true=1 and false=0 in your new Python window or at the top of your script.

In general, start with all the following commands:

>>> import sys
>>> import time
>>> import datetime
>>> import requests
>>> import json
>>> >>> true=1
>>> false=0