Q&A Viessmann API

[MichaelHanna]

Dear developer and smart home enthusiasts,

today, we want to contact you to talk with you about the recent activities that are taking place concerning the interface of the heating systems, also known as the Viessmann API. As most of you might have already received our Email in which we informed you about the upcoming changes concerning the use of the API, we would like to open this thread to continue the discussion openly and transparent with you and pick up on the discussions in this thread. Here is again a brief summary of the main points from our message:

> As Viessmann, it’s in our responsibility to provide our users with reliant and safe products, including features and services around those products

> We are impressed to see your interest in connecting and interacting with your heating system and that you found a solution for your specific use case without a description or support from our side

> However, it challenges us to check and channel the method and frequency of requests to our IoT Services in order to keep those stable and available for all our users

> What is even more important is that for these solutions, we as Viessmann currently cannot guarantee a safe and reliant operation of your heating system

This has the following steps that we have to take:

> In order to keep operation through our API safe and still give you the chance to interact with your system, we limit the use for all applications by setting a threshold for the requests. The limit is set for both a larger (e.g. daily) and a smaller (<15 mins) time scale. Reaching the limit will prevent you to execute any further requests with your account in the specific time frame. So please make sure to adapt the frequency of the requests of your current solution to avoid reaching the limitation.

> We are heavily working on providing a solution for all users that is 1) approved & safe to use, 2) properly explained and 3) gives you the functions and information you need for your specific use case. At the same time, this will also be moment when the solution is in place where we cannot allow any other ways of accessing our API. To make things clear: Your already built and currently used functions will still be able to use, it’s only that you will need a new API client provided through the Portal that can be self-managed by the user himself.

We also received a lot of questions via Mail and also in this forum, which we are going to answer for everyone individually. We also saw that the most common question among the responses was the demand for a local API. This is a reasonable request and we appreciate and take the demand very seriously. However, we will not able to provide you a solution for this in the near future. This feature (as all other features and requests by users) are permanently discussed and evaluated and brought together with all other strategic decisions that Viessmann is taking.

I again would like to encourage everyone to participate in the development and make sure to sign in here to get an early access to the Developer Portal. Also, we are hoping to have a constructive discussion here in this thread. We are really looking forward to work jointly together with you on ideas and co-create future solutions!

P.S.
As stated in the previous thread and in certain Emails we received, we are aware that some users might expect a communication in german from us, as Viessmann is of course a company with German heritage. However, since we are providing climate solutions all over the world and especially programming / APIs is natively described in english, there is no other option than communicating in english first. This has already been greatly explained by @thetrueavatar in the previous thread.

All the best!

Michael Hanna

Viessmann Developer Portal

EDIT:

In order to support you more on adjusting your current solutions according to the current limitation, here is how the threshold works:

We have a rate limit with sliding window. Whenever the first request arrives, we open a time window and count all request in that window. If the number of requests reach the limitation, we block all incoming user requests until the time window ends. Then, with the next user request, a new time window opens.
Currently, we have the following limits active:
120 calls for a time window of 10 minutes
1450 calls for a time window of 24 hours
Please take note that we are taking the right to adjust the limits if seen necessary. Information about adjustment of the threshold will be given with a reasonable amount of time in advance for all affected user.

EDIT2:

For all who experienced a ban after the limitation time frame with a few number of API requests: Our team fixed an issue with the limitation, which is taking effect since today and should solve this problem. We are still analyzing the behavior, but for now it looks ok.

[Croydon]

Dear Michael,

thank you for the explanation which was really misleading in the mail sent.

> The limit is set for both a larger (e.g. daily) and a smaller (<15 mins) time scale.

Can you further explain what exactly is the limit of the larger and smaller time scale? This is important to know imho.

Thanks and best regards

[phildaub23]

This is actually great news! I misunderstood your first email and thought you would completely deny any further access to your existing API and build a new one, but now I get it - you enable us makers to get own API application ids and keys. This is an absolutely reasonable thing to do and ensures your service to be more resilient against clients with high request frequency and also makes it measurable.

Looking forward to the dev portal - I already signed up for the beta!

PS: I plan to support the community by contributing a C# .NET Core open source client for the Viessmann API once it is officially available.

[johandb]

I have lowered the frequency of accessing the Viesmann API to 20 minutes. Would that allow access again for both my Openhab application (using the 'Thetrueavatar' php api) as well as my Vicare app ?

[MichaelHanna]

Thank you @phildaub23 for bringing it on the point! And sorry for any misleading information that the previous mail had caused.
Looking forward to co-develop!
Best,
Michael

[thetrueavatar]

Hello,

Could you please give us more accurate information about the treshold ? Is this a global treshold for every features or different one for each feature ? So, basically, we need to set a polling interval of 15 minutes at least ? Is this treshold the same for ViCare ? Does it means we aren't allow to change value twice in 15 minutes ?

[joozzt]

Hi, looks good, thanks ! Would be good if the API allows batch downloads of data, this will limit the number of API requests while maintaining a good resolution in time for analysis. Preferably a 1 min resolution or lower.

At the moment I only need 4 requests per day, for adapting supply temp of  heating pump to weather forecast. But request every Min for analysis, which I personally don't need real-time, once each 15 min would be great.

Local access would be best, like sunspec for solar panel inverters, opentherm access would make things standardized for you and us. I don't know the specifics of Opentherm but if you can download historical data like I do now, that would be great.

[JayVee99]

Dear Michael,

Thanks for clarification. I haven't received a notification mail and just logged into this forum, when login to API failed.

Just to give you some user's feedback how the API is used:

I'm one of the users who polled the API once a minute to read out most inportant data and fill it into an SQL database to see change of water temperature, pressure, burner oszillations and so on.

You are right that 15 minutes polling interval might be enough for most users. But especially to see the burner oscillations a shorter interval of maybe 5 mins would be more convenient.

I also would prefer to read out local data instead of polling your servers, if this is possible.

Thanks,

jayvee

[eweri]

Hello Michael!

I use the API to read the data into my volkszaehler.

Sorry but i can not accept that Viessman would limit access to the data of my heating system. 

I give Vissmann my data for free - and lots of other give thier data for free also, so Viessmann could build up "Big Data" and try to find in this data something that is important for Viessmann. Thats okay as long as I get unrestricted access to my data.

I bought a Vitoconnect 100, just to find out that I get no data from this device within my LAN - only via iOS-App. That was very disappointing.

I want to get --my-- data from --my-- heating system on minutely basis. 

So to satisfy my need, i suggest one out of two solutions:

1. Upgrade the firmware of the Vitoconnect 100 for example with a static web-page that presents all parameters with its current value - so I can access the data on a 5th secondly timeframe (if i want to) and your servers do not have to cope with the load that such a timeframe would produce. This solution is independant from any API. Private users use the LAN access and professional users could use the API. Your servers just need to satisfy a few professionals.

2. Install more powerfull servers and create an API that is not so demanding on the hardware. At the end you have more clients that access this API. So a change in that API would generate a lot of unsatisfied customers. I suggest 1 is the better alternative. 

I think it is fair to give someone access to its own data on a minutely timebase, because you get that data for free. The users even had paid for a device that gives no benifit to them other than an iOS-App where is no export possible. BTW. i want to know what my heating system is doing now and not what did my heating system one hour or a day ago.

Just my two cent.

Christoph

[Zbig]

Hello Michael,

it would be very interesting when Viesmann would publish the numbers about the traffic caused by Vitoconnect / ViCare / VitoGuide, also under historic point of view.

In my opinion the traffic increased very fast caused by the non-standard usage which was not awaited by Viessmann at the beginning.

The calculation in the management was made surely only based on VitoGuide and Vicare tests with a 5% reserve for the nerds.

Now Viesmann has to deal with a crowd of experts that tune their home automation without using ViCare or VitoGuide because they are not useful for real automation. They are very useful for quick check or a quick adaptation beeing out of home. But not for automation.

And automation is what we really want when there is a cable connected to the Viessmann device which we can access on the other end.

In my case I have made a nice integratoin where the thermostates trigger the Viessmann device to work or not - independent of the heating internal program which cannot react. I can could increase the wished temperature at any thermostat (far away from the heating) which triggered via openhab / thetrueavatar-api changing mode of the heating. Without going to the cellar. Without grabbing my telephone. Whith saving a lot of money. But I am only an amateur.

I would like to encourage Viessmann to consider how many people and at which level have already implemented their automation of the heating at home to get comfortable and to save money (Just check the setting-commands in the traffic.). This would not work without Optolink / Vitoconnect. And thi is great.

I would further like to encourage VIessmann to consider a local access to the heating system using Vitoconnect. This would give a chance for all the high level automation implementations out there and would solve the traffic problem at Viessmann.

Other wise, I think, the experts will pull the Optolink cable from Vitoconnect and connect it to a next Raspberry-Pi instead. But maybe this is the strategy of Viessmann?

Best Regards

Zbig

PS.

It would be much easier for the user if Viessmann would first introduce the API, let the people use it for their integrations and afterwards restrict the access to the server that are forseen for ViCare/Vitoguide. We are now discussing access restrictions instead of the art and state of the API....

[ravanimi]

Dear Michael

I think Viessmann is making a mistake by not leveraging the passion, effort and brains of a community that was able to build sophisticated monitoring and controlling layers to your products without a single bit of documentation (!).
Simple solutions can be implemented that would provide the local, near real-time monitoring the owners wish and the full control on the parameter changing process that Viessmann needs while at the same time decreasing the load on the company's infrastructure.
I am sure that when provided with the low(est) level API, requirements and guidelines (the law), and the documentation, the community will respond by building more complex data collecting, storing, displaying, monitoring, etc. services and applications that Viessmann would be able to leverage to reduce the development cost and shorten the time to market of their desktop applications and mobile apps. It would be a pity to miss such an opportunity

Kind Regards
Michele

[Zbig]

I agree that it is not very fair that Viesmann has got all the data at any time and the user is restricted to have an insight only every 15 minutes. I can already observe that everybody that wants "constant access" writes about that he is used to collect data every minute and not lower. This is the value at which the API should be oriented to be able to process all the communication. This would solve the whole problem. Restrictions would not be even needed.

[schueli86]

Hello everybody,
I registered here once because I am also affected by the change. I increased the interval to 30 minutes, but unfortunately I haven't had a connection since yesterday. Is my account blocked for further use of the API?

Unfortunately I did not receive the email and would also like to register for the developer portal. Where can I register?

[JueBag]

Since the 16 April around 15:30 UTC I am unable to get data via the API and my ViCare is no longer connected to the server. My time-interval was set to collect data every minutes.

It was really "nice" to send the above "clarification" on those restrictions before they went into effect. The "clarification" does neither clarify how to corectly implement them ( a request every two days is out off bounce?) nor was it send in time to allow anybody to react on it.

[PWeber]

Dear Viessmann team,
I think you're on the wrong track here. Surely it is commendable when you publish an API. But you see the need here for local access to the heating system data. For optimization, a close monitoring of the data is essential. With a greatly reduced query interval, it is impossible, for example, to detect a pulsing burner and the reason for it. You can really set yourself apart from the competition in a positive way at this point if you act correctly now. But you can also scare away all enthusiasts in the long term if you make the wrong decisions.

Best regards
Philipp Weber

[phildaub23]

Update: unfortunately, I do not get any values anymore since yesterday early afternoon 😞 I thought it would eventually reset **bleep** midnight (24h rate limit counter) but still no values...

My request frequency is each value every 5 min, which should be fair use of your servers - even the ViCare App is chattier if opened.

Can you please remove the throttling immediately again as it (obviously) doesnt work as you intended. You should wait for the release of the dev portal and concrete documentation of rate limits, give everyone the chance to update their settings/implementation and then activate the rate limit throttling.

[DonVito]

Liebes Viessmann Team,

ich habe als API-Nutzer ebenfalls Ihre E-Mail bekommen und wurde dann direkt gestern damit konfrontiert, dass meine Automation, die ich über ioBroker und den dafür frei verfügbaren, von einem Community-Mitglied entwickelten Adapter realisiert habe, nicht mehr funktioniert. Das Ganze lief im Zusammenspiel mit einer Anwesenheitserkennung, wodurch ich natürlich die Warmwasserbereitung etc nur auf solche Zeiten beschränke, in denen auch wirklich jemand zu Hause ist. Das ist durch eine reine Zeitprogrammierung natürlich nicht zu erreichen. Die damit einhergehende Ersparnis an Energie geht mir natürlich dann ab jetzt ebenfalls verloren.

Aus den aktuellen Diskussionen rund um das Thema Nachhaltigkeit und Klimaschutz würde ich es daher sehr schätzen, wenn Sie doch bitte wieder die API freigeben, weil dadurch sicher nicht nur bei mir, sondern auch bei vielen anderen Nutzern Energie eingespart wird.

Weiterhin weiß ich ja auch nicht, was Ihre Controller an zusätzlichem Gewinn errechnet haben, wenn man für die Nutzung der API-Schnittstelle zahlen müsste. Aber hier frage ich Sie mal ernsthaft, ob das für Sie vertretbar wäre, würden vorherige Nutzer das nicht unterstützen und lieber mehr Geld an Ihren Energieversorger zahlen?

Aus meiner Sicht ist das gerade in der heutigen Zeit ein absoluter Rückschritt, was Sie hier gerade versuchen umzusetzen. Sie machen damit nicht nur Ihre Produkte für potentielle neue Kunden uninteressant (ich würde zumindest aktuell niemanden mehr ein Viessmann-Gerät empfehlen) sondern riskieren scheinbar auch einen erheblichen Imageschaden durch das Blockieren der Energiesparversuche Ihrer aktuellen Kundschaft.

Denken Sie mal drüber nach ...

[r2h2]

I wonder if Viessmann is using an API gateway, such as 3Scale. These products should offer a straightforward solution to the problem by throttling the traffic to a certain threshold that can be published as a "fair use" limit. Users requiring more traffic would have to enter a special agreement. This is a standard approach with many API providers.

I hope Viessmann does not reinvent the wheel and reuses established practices and products. BTW, if you would do open source parts of your products you could get more support from the community.

[thetrueavatar]

I think people have to understand how cloud based service works. Company are no more using server on premise but rent a hosting in a cloud service(such as Azure, AWS,...) . This allow company to scale on demand. However, for this rent, the billing is based on throughput( the number of client and request). So it's natural that Viessmann in a first attempt will avoid to be overloaded. Moreover, now that it will be an official API they will have to provide a SLA(service level agreement) which define maximal time for a response, number of request or client /minute supported... Current user of the api with the community script are kind of underground user. As soon as they will open to every user the througput will be more than likely quite important. If they want to provide a high available/stable service to every user they have to monitor/control how much request they will receive. Some people may(intentionally or not) literaly spam the API resulting in DDOS attack...

Of course, one solution would be to have a local server to avoid spamming their api but this doesn't seems to be planned shortly.

[Croydon]

@thetrueavatar
while this is totally true, the de-facto-shutdown of the current API before having the new one ready is a real problem for home automation. To have the optimizations work and all the scripts for PV, Heating etc. working, I need to query regularly, i. e. at least about once a minute. And I have to change temperatures regularly, too. So there is still no information about how the threshold is working exactly. My access got locked, too, since yesterday. And that is quite a problem for the heating control.

[thetrueavatar]

Same for me. I have set my cron to ask every 20 minutes to get some basic information but my account is still blocked:
- slope/curve
- active mode
- active program
- external temperature
- room temperature
- boiler temperature
- heating burner status
- heating and water schedule
- normal and reduced program's temperature

So please could you be more accurate on how the treshold works ? For instance for each information I do a call. If it's a global threshold for every feature then I will update my code to get all information in only one call. That's not a problem but please provide us exact and accurate information.

[thetrueavatar]

Ok I have been digging into the error received here is what I have received as response:
{
"errorType": "RATE_LIMIT_EXCEEDED",
"extendedPayload": {
"clientId": "XXXX",
"limitReset": 1584462010106,
"name": "ViCare day limit",
"requestCountLimit": 1450,
"userId": "XXXX"
},
"message": "API calls rate limit has been exceeded. Please wait until your limit will renew.",
"statusCode": 429,
"viErrorId": "XXX"
}

The problem is that 1584462010106 is 17 march 17h20... It's way too long as limit reset datetime !!!!!!
BTW what does requestCountLimit means ? I guess it's a counter but when does this counter reset ? 1450 is quite a huge number of call indeed. I have the feeling that your reset policy extend the ban of an amount of time for every call behind the limit. I would expect the reset would be **bleep** a minimal idle time since the last call....

[thetrueavatar]

Ok I have been digging into the error received here is what I have received as response:
{
"errorType": "RATE_LIMIT_EXCEEDED",
"extendedPayload": {
"clientId": "XXXX",
"limitReset": 1584462010106,
"name": "ViCare day limit",
"requestCountLimit": 1450,
"userId": "XXXX"
},
"message": "API calls rate limit has been exceeded. Please wait until your limit will renew.",
"statusCode": 429,
"viErrorId": "XXX"
}

The problem is that 1584462010106 is 17 march 17h20... It's way too long as limit reset datetime !!!!!!
BTW what does requestCountLimit means ? I guess it's the maximum limit  but when does this counter reset ? 1450 is quite a huge number of call indeed. Your reset policy seems to extend the ban of a fixed amount of time when we exceed the limit.  But once we reach the datetime reset does this count reset to 0 ? I have the feeling that the banned attempt are being counted as well in the total amount of allowed request/day ? This should be 1450 succeed request !

Moreover  I would expect the reset would be a minimal idle time since the last call....

This limit is pretty a non-sense with the HATEOAS approach of the current API. This approach is use for flexible api where the api needs to be discovered bit by bit. So this approach force client to do multiple call instead of a big one..

[eweri]

Hello!

Same for me - maybe we should disconnect our VitoConnect 100s from the Internet as a protest?

[adorobis]

Dear Michael,

Apart from emphasising the need for access to the data from the heating system I have purchased from Viessmann, additional component that wasn't for free either I support previous opinions that this is our data.

Anyway could you please clarify 2 main open questions:

- what are the actual daily and 15 minutes limits and when do they reset? Now even my mobile app stopped working and I don't know when it will be back online.

- what is the intention behind the Developer Portal? What type of contribution do you expect from the developer community and what benefits do you intend to offer?

Kind regards,

Adam