Using the API
Let’s get started with the ToonAPI. We will take you through some of the functionality of the API step by step. If your questions aren't answered on this site, please contact us at devsupport@toon.eu. If you’re already familiar with the ToonAPI, you might want to jump straight to the Swagger definitions. In our examples, we will use Curl. If you’re on Linux or OS X, you already have it installed. Windows users can get it here. You can simply copy and paste the examples, but you will need to replace certain values with information that applies to your situation.
Getting started
First of all, you need to get some credentials. Get this information by creating an account on this site. To authenticate yourself with the ToonAPI, you’ll need a Consumer Key and a Consumer Secret. Find out more about that at our authentication page. Once you have logged in you can go to My Apps in the drop-down menu under your name. Click on the Add App button and fill out a name for your application and a Callback URL for the OAuth2 flow.
Note that the Callback URL needs to be a well-defined URL according to https://tools.ietf.org/html/rfc6749#section-3.1.2, authentication will fail otherwise. These need to be reachable from the browser that does the authentication requests. If you need more than one, you can add multiple entries separated by a comma without whitespace. Some examples:
- http://localhost:8080/authorize
- https://my.secure.site/and/path/?query=supported
- http://localhost:8080,http://localhost:3000
- my-app-proto://authorize
- localhost:8080 this will not work!
You should now be able to see the following information:
Your-apps’s Keys Consumer Key 0o000o0o0o0o0o0o0o0o0o0o0 Consumer Secret ooo0o0ooo0o0o Key Issued Wed, 09/06/2017 - 13:01 Expires Never
The key and secret identify your app. Use this to gain access to the Toon that you wish to connect to. Still confused? Don't forget to check out our authentication page.
Getting agreementId
An agreementId is a value that lets the API know from which Toon you are getting your information. Values you need to fill out yourself are in curly brackets.
curl -X GET \
https://api.toon.eu/toon/v3/agreements \
-H 'authorization: Bearer {access_token}' \
-H 'cache-control: no-cache' \
-H 'content-type: application/json' \The result will be:
[
{
"agreementId": "1111",
"agreementIdChecksum": "o0o0o0o0oo0oo0o0o0o0o0o0o0o0o0o0",
"heatingType": "GAS",
"displayCommonName": "eneco-001-1111111",
"displayHardwareVersion": "qb2/ene/3.7.9",
"displaySoftwareVersion": "qb2/ene/3.7.9",
"isToonSolar": true,
"isToonly": true
}
]
Congratulations! You're well on your way to do some cool stuff. Important now is, that you keep the "agreementId" as well as the "displayCommonName". You will need them to address this specific display as well as in the headers of any following api call.
Getting recent usage and production data
Want to get your hands on the gas and electricity usage of the last 24 hours? There are endpoints that retrieve this information at 5-minute intervals. For this example, we will get the information from https://api.toon.eu/toon/v3/{agreement}consumption/electricity/flows. Other endpoints for gas usage and electricity production work similarly.You can find the other endpoints in the swagger documentation. Values you need to fill out yourself are in curly brackets.
curl -X GET \
https://api.toon.eu/toon/v3/{agreement}/consumption/electricity/flows \
-H 'accept: application/json' \
-H 'authorization: Bearer {access_token}' \
-H 'cache-control: no-cache' \
-H 'content-type: application/json'
-H 'X-CommonName: {displayCommonName}' \
-H 'X-Agreement-ID: {agreementId}' \The result will be:
{
"hours": [
{
"timestamp": 1506408600000, // Epoch timestamp
"unit": "W", // In this case the value is measured in watts
"value": 1000
},
(..rest of the object)
Please note that the array is called hours, but the interval between values is actually 5 minutes.
Getting historical usage and production data
There are endpoints to get all the usage of gas and electricity that is stored on Toon. For this example we will get the information from https://api.toon.eu/toon/v3/{agreement}/consumption/electricity/data. Other endpoints for gas usage and electricity production work similarly. You can find the other endpoints in the swagger documentation. Values you need to fill out yourself are in curly brackets.
curl -X GET \
https://api.toon.eu/toon/v3/{agreement}/consumption/electricity/data?interval={interval}&fromtime={fromtime}&totime={totime} \
-H 'accept: application/json' \
-H 'authorization: Bearer {access_token}' \
-H 'cache-control: no-cache' \
-H 'content-type: application/json'
-H 'X-CommonName: {displayCommonName}' \
-H 'X-Agreement-ID: {agreementId}' \The interval can be set to hours, days, weeks, months or years; the default interval is hours. "fromtime" and "totime" denote the timeframe from which you will receive the data given in epoch timestamp. The default timeframe depends on the interval given. This is 24 hours ago in case of hours; 7 days ago in case of days, etc.
The result will be:
{
"hours": [],
"days": [],
"weeks": [],
"months": [
{
"timestamp": 1472680800000, // Epoch timestamp
"unit": "Wh", // In this case the value is measured in watthours
"peak": 100000,
"offPeak": 100000
},
(..rest of the object)
Setting the thermostat
You can get the thermostat information from https://api.toon.eu/toon/v3/{agreement}/thermostat
curl -X GET \
https://api.toon.eu/toon/v3/{agreement}/thermostat \
-H 'accept: application/json' \
-H 'authorization: Bearer {access_token}' \
-H 'cache-control: no-cache' \
-H 'content-type: application/json' \
-H 'X-CommonName: {displayCommonName}' \
-H 'X-Agreement-ID: {agreementId}' \The result will be:
{
"currentSetpoint": 1050, // Current target temperature for the thermostat
"currentDisplayTemp": 2150, // Temperature that is currently on the display
"programState": 0, // State of the weekly thermostat schedule (see below)
"activeState": -1, // Which programmed setting is active (see below)
"nextProgram": -1, // Program type that will be active after the current entry ends.
"nextState": -1, // Which programmed setting will be used after the current one ends
"nextTime": 0, // Time next programmed setting starts
"nextSetpoint": 0, // Which target temperature will be used by the next activeState
"errorFound": 255, // 255 means everything ok. Anything else means there is trouble
"boilerModuleConnected": 1, // Boilermodule connected or not
"realSetpoint": 1050, // The setpoint that is really active based on the program or manual setting
"burnerInfo": "0", // Burner state (see below)
"otCommError": "0", // info if there is an issue between the boilerModule and the boiler. Will only work for OpenTherm boilers
"currentModulationLevel": 0, // Value between 0% and 100% indicating the level that the boiler is heating at. Will only work for OpenTherm boilers
"haveOTBoiler": 0 // Value that indicated if a OT boiler is connected.
}
ProgramState:
- Program is off = 0,
- Program is on = 1,
- Program is on, user temporarily want different setpoint = 2
activeState:
- Comfort = 0,
- Home = 1,
- Sleep = 2,
- Away = 3,
- Holiday = 4
burnerInfo:
- burner off = 0,
- burner on = 1,
- burner heating for hot water = 2,
- burner preheating for the next setpoint = 3
Using the webhooks
With the webhooks function, you can receive data from the Toon on a URL. The subscription time is 3600. If you want, you can resubscribe after that. The minimum information that you need to give before starting webhooks is applicationId and callbackUrl. Optionally you can specify which type of information you would like to receive. If not specified you will subscribe to Thermostat, SmartPlug, SmokeDetector and BoilerErrorInfo. If you want to subscribe to the current power usage you will always need to specify this. Please note that subscribing to power usage will result in getting an update every 10 seconds. This can really add up if you connect with a lot of displays. You can start a webhook with the following call:
curl -X POST \
https://api.toon.eu/toon/v3/{agreements}/webhooks \
-H 'authorization: Bearer {access_token}' \
-H 'cache-control: no-cache' \
-H 'X-CommonName: {displayCommonName}' \
-H 'X-Agreement-ID: {agreementId}' \
-d '{
"applicationId": "{client_id aka consumer key}",
"callbackUrl": "{url}"
"subscribedActions": [
"PowerUsage"
]
}'The result will be just a 200 OK
- ApplicationId: The name of the App that you made in your user profile on this site.
- CallbackUrl: URL on which you will receive data from Toon. This value is not the callbackUrl you use in the oAuth flow.
If you want to know which webhooks are active for you, you can use the following command:
curl -X GET \
https://api.toon.eu/toon/v3/{agreement}/webhooks \
-H 'authorization: Bearer {access_token}' \
-H 'cache-control: no-cache' \
-H 'X-CommonName: {displayCommonName}' \
-H 'X-Agreement-ID: {agreementId}' \The result will be something like this:
[
{
"applicationId": "{clientid aka consumerkey}", // The name of your app
"callbackUrl": "https://www.someexample.com", // The Callback URL that you specific
"clientUuid": "0o00o0o0o0o0o0o0o0o0o0o0o0o0", // The access token that associated with the display
"subscriptionTime": 1507294807891, // Time that the subscription started, maximum subscription time is 1 hour
"subscribedActions": [
"Thermostat", // Data regarding the thermostat
"SmartPlug", // Data regarding Fibaro Smartplugs that are connected to Toon
"SmokeDetector", // Data if smoke detector is present
"BoilerErrorInfo", // Data regarding boiler errors
"PowerUsage" // Data regarding current usage of electricity.
]
}
]
If you want to end the webhook registration, you can do so by using the following command:
curl -X DELETE \
https://api.toon.eu/toon/v3/{agreement}/webhooks/{consumerkey} \
-H 'authorization: Bearer {access_token}' \
-H 'cache-control: no-cache' \
-H 'X-CommonName: {displayCommonName}' \
-H 'X-Agreement-ID: {agreementId}' \