API walkthrough

For this tutorial, we use the curl tool that is available as standard on most mac and linux computer (the windows version can be downloaded at https://curl.haxx.se/download.html). You can try each command directly on your computer, by replacing the access token in each command with a fresh access token. 

Known API issues and limitations

No API is perfect, and there are some known issues and limitations with the current Toon API. We have listed the most important issues and limitations here so you know what to expect. If you encounter other issues during testing, report them to us and we will immediately list these and put them on the product backlog for fixing. 

  • The Swagger documentation cannot be used interactively. There is no authentication option available. 
  • The Swagger documentation shows http://. This is incorrect, you should always use https://
  • The Virtual Toons do not respond correctly to PUT and POST methods. This functionality has not been implemented
  • The /status/ command has been optimized for repeated use, and this has made the function unpredictable: it only sends differences with the last call. 
  • There are many different names and terms used through the API and the meaning of each term is not always obvious. We are working on an Toon API terms list to explain each term. 

Getting started

In order to get access to a Virtual Toon for testing, you need to sign up and get access details via email. You will get the following data via email: a password, key and secret. 

E-mailaddress: something@domain.com
Password: <random password>
Key: <random key>
Secret: <random secret>

Get access token

In order to use the API you have a get a new, fresh access token. These tokens expire after a certain time for security reasons, so almost any sessions begins with getting a new token. The command needed is:

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=password&username=<email address>&password=<password>&client_id=<key>&client_secret=<secret>" https://api.toonapi.com/token

{"scope":"default","token_type":"bearer","expires_in":3291,"refresh_token":"b13d6faa5bb1853e891df578cb890d1","access_token":"<access_token>"}

Get agreements

The agreement is the value that lets the API know which Toon you are getting the information from. In theory one user can have more than one Toon. To get all available agreements use the following command:

curl -X GET -H "Authorization: Bearer <access_token>" https://api.toonapi.com/toon/api/v1/agreements

When you use the credentials for the virtual Toon you will get a response that looks like this.  

[{"agreementId":"quby.virtual.4321","street":"Joan Muyskenweg","houseNumber":"22","postalCode":"1096CJ","city":"AMSTERDAM","displayCommonName":"qb2-haet-54975968-8ff6-4f1f-bd98-477e3a81b2e4","displaySoftwareVersion":"qb2/ene/2.7.14"}]

Post agreements

The following command will let the API know which agreement you want to use. In other words which Toon you want to send the API calls to. The agreement will remain active as long as requests are being made to the API. After about 5 minutes of inactivity the API backend forgets about the agreement and you’ll need to POST the agreement again. Here's the command you need: 

curl -X POST -H "Authorization: Bearer <access_token>" -H "Content-Type: application/json" -d '{"agreementId": "<agreementid>"}' https://api.toonapi.com/toon/api/v1/agreements

Get temperature and other status information

The best way to get the temperature is to use GET status. You need to fill in the access-token in order to get the status. The status contains the current temperature. After posting the agreement you will receive a long status update. Subsequent status calls will give you the difference between the long status that you received and the current status. This can result in an empty response.

curl -X GET -H "Authorization: Bearer <access_token>" https://api.toonapi.com/toon/api/v1/status

Here's an example of a response:

{"success": true, "thermostatInfo": {"currentTemp": 2000, "currentSetpoint": 2250, "currentDisplayTemp": 2250, "programState": 0, "activeState": -1, "nextProgram": -1, "nextState": -1, "nextTime": 0, "nextSetpoint": 0, "randomConfigId": 1804289383, "errorFound": 255, "boilerModuleConnected": 1, "realSetpoint": 2250, "burnerInfo": "1", "otCommError": "0", "currentModulationLevel": 100, "haveOTBoiler": 0}}

As you can see, the temperature for this virtual Toon is 20 degrees celsius (2000 divided by 100). The current ProgramState is 0. As you can read in the non-technical description, this means "Comfort". The other starts are Home (1), Sleep (2) and Away(3). 

As long as the agreement is active you will receive the short status upon requesting the status after the first long status. If the agreement runs out and is posted again you will receive the long status again. 

Change the temperature and state

You can use PUT functions to make changes. The following example shows how to set a new target temperature.

curl -X PUT -H "Authorization: Bearer <access_token>" -H 'Content-Type: application/json' -d '{"value":1900}' https://api.toonapi.com/toon/api/v1/temperature

As we explained in the non-technical explanation, for many apps it is more useful to change the state than it is to change the target temperature. Most users have configured the ideal temperatures for four different situations: Home, Away, Sleep and Comfort.  To change the state to Home, use the following call. 

curl -X PUT -H "Authorization: Bearer <access_token>" -H 'Content-Type: application/json' -d '{"state":"0", "temperatureState":"1"}' https://api.toonapi.com/toon/api/v1/temperature/states

The command itself does not return any value. You need to check the result with a new GET status. The result should look like this. As you can see, the Virtual Toon does not change state, this function has not been implemented yet.

{"success": true, "thermostatInfo": {"currentTemp": 2000, "currentSetpoint": 2250, "currentDisplayTemp": 2250, "programState": 0, "activeState": -1, "nextProgram": -1, "nextState": -1, "nextTime": 0, "nextSetpoint": 0, "randomConfigId": 1804289383, "errorFound": 255, "boilerModuleConnected": 1, "realSetpoint": 2250, "burnerInfo": "1", "otCommError": "0", "currentModulationLevel": 100, "haveOTBoiler": 0}}

Get consumption data

You can in theory use the API for getting consumption data. The examples below shows how this would work in theory. The examples however do not work on the Virtual Toon that is used in this walkthrough. 

To use this function, you need to specify times using milliseconds since the UNIX epoch. You can use https://currentmillis.com for converting normal dates to this format. Here are some valid values that you can use for testing: 

  • 1467324000000 [2016 july 1  00:00] 
  • 1467410400000 [2016 july 2 00:00] and 
  • 1468841977196 [2016 july 18 13:39]

We use these values for making the following requests. 

curl -X GET -H "Authorization: Bearer <access_token>" -H 'Content-Type: application/json' -d '{"fromTime":"1467324000000","toTime":"1468841977196","interval":"Days"}' https://api.toonapi.com/toon/api/v1/consumption/electricity/data
curl -X GET  -H "Authorization: Bearer <access_token>" --header "Accept: application/json" "https://api.toonapi.com/toon/api/v1/consumption/electricity/data?fromTime=1467324000000&toTime=1468841977196&interval=Days"

The result is empty: the Virtual Toon does not support this function.
You can also use the flows command for getting the same data in a different format. You can for instance use the following format:

curl -X GET -H "Authorization: Bearer <access_token>" https://api.toonapi.com/toon/api/v1/consumption/electricity/flows?fromTime=1467324000000&toTime=1468841977196

For our Virtual Toon, you receive one value back. 
[1] 33539

Next steps

Have a look at the Developer journey for an overview of all available documentation.