API Documentation

The Energy Data API

Our database and the calculation of Heating Degree Days and Cooling Degree Days are available via an API (Application Programming Interface). This interface allows energy managers, developers and other projects to access individually calculated data.

To request data, you need a valid API key, which you will receive via our subscription service. The format of the data output is CSV (comma separated values) or JSON (JavaScript Object Notation).

The Data Query

Before our server can do a calculation for you, it needs to know what you want calculated. To tell the server what you want calculated, send us the parameters of your request in a special format (URL). Every request URL is unique accord to your specific case.  

Our server will only accept requests that include a correctly formatted URL. So be aware of typos.

Tip: Use the “DEGREE DAY Calculator PRO” for a comfortable and efficient way to automatically generate a valid request URL. No more struggling with technical documentation – just copy & paste the URL into your software. 

https://api.energy-data.io/degreedays/{indicator}/{method}/?{paramaters}

The choice of the {indicator} (Heating and Cooling Degree Days or “Room Heating Degree Days” (Gradtagzahl)) determines which {parameters} must be defined. The {method} defines the used calculation method to be used. The required parameters will be described in the following chapter.

{indicator}

Choose the required energy indicator and use the highlighted abbreviation for your query:

• hdd – “Heating Degree Days”
• cdd – “Cooling Degree Days”
• dd – “Room Heating Degree Days” (method for Heating Degree Days that includes the desired room temperature, German: “Gradtagzahl”)

You don’t know which indicator to pick? Read here in our article, about the different Degree Day indicators.

Note: the normalization of heating consumption according to ISO 50001 is usually conducted using Heating Degree Days (hdd).

{method}

Wählen Sie als nächstes die gewünschte Berechnungsmethodik aus:

• int – “Integration Method” (Integralmethode)
• mean – “Mean Temperature” (Tagesmitteltemperatur)
• mima – “Min./max. average Temperature” (Min.-/Max.-Durchschnittstemperatur)

Note: We recommend the use of the integration method because it uses all available temperature reading points. However might need to use the less precise calculation methods for local requirements.

{parameters}

You can use the parameters to describe the boundary conditions for your individual calculation request and authorize the request with your API key.

The parameters are listed one after the other in the last part of the URL and are separated from each other with ‘&’ characters. The order of the parameters is not predefined.

Example: https://api.energy-data.io/degreedays/hdd/int/?paramater1=xyz&pmeter2=xyz&pmeter3=xyz

Location (station=)

Find the nearest weather station for your location using our interactive map. Several formats can be used for a query:

• Station ID – Energy Data internal ID, format: string, e.g. station=DE_EDDH (recommended)
• ICAO ID – International Civil Aviation Organization ID used for airports, format: string; e.g. station=EDDH
• WMO ID – World Meteorological Organization ID, format: “WMO“+integer, e.g. station=WMO10147
• National ID – national ID used by local organizations, format: alpha 2 ISO country code; e.g. station=DE01975

Start Date of Calculation Period (start=)

• yyyy-mm-dd – e.g. start=2010-01-01

End Date of Calculation Period (end=)

• yyyy-mm-dd – e.g. end=2020-12-31
• Todays Date – end=today

Base Temperature (tb=)

Heating Limit for Heating Degree Days or Cooling Limit for Cooling Degree Days in °C.

• Format: float (with decimal point), e.g. tb=15.0

Room Temperature (tr=)

The desired room temperature only for calculation of “Room Heating Degree Days“ (German: “Gradtagszahl”).

• Format: float (with decimal point), e.g. tr=20.5

Result display (breakdown=) – optional

The parameter “breakdown” defines the aggregation by time:

• daily – results for each day (default); breakdown=daily
• weekly – result aggregated by week; breakdown=weekly + week_start=[weekday]
• monthly – results aggregated by months; breakdown=monthly
• yearly – results aggregated by years; breakdown=yearly

Format- optional

Chose the output format:

• csv – comma separated values (default)
• json – JavaScript Object Notation

API Key (key=)

Your personal API key you recieved via email with your order confirmation.

• e.g. key=762a4bb6-c05b-4349-9663-de6d5550aaac

Example

You want to query the Heating Degree Days (hdd) for Hamburg Finkenwerder (ICAO ID: EDHI, WMO ID:10149) for the year 2020 with a Heating Limit (tb) of 15°C. You want to apply the precise Integration Method (int):

https://api.energy-data.io/degreedays/hdd/int/?station=DE_EDHI&start=2020-01-01&end=2020-12-31&tb=15&key=762a4bb6-c05b-4349-9663-de6d5550aaac

Output

The requested energy indicators are calculated on our servers according your customized parameters and transmitted in CSV format. CSV stands for comma seperated values. The file can be read into all common databases or accessed with import function within Microsoft Excel.

The first lines of the file is the header which lists the specifications for the calculation.

The lower part lists the calculated values with corresponding time stamps.

The example of the Heating Degree Days for Hamburg is returned as follows. Since no specification was made for the ” breakdown”, the results are given as daily values by default.

Indicator;Heating Degree Days
Method;Integration Method
Base Temperature;15
Unit;Celsius
Station;DE_EDHI, Hamburg Finkenwerder, Deutschland
Coordinates;53.536, 9.837
Description;Heating Degree Days with a base temperature of 15C based on integration method
Source;https://energy-data.io/

Date;HDD (15)
2020/01/01;15.69
2020/01/02;15.54
2020/01/03;9.17
2020/01/04;10.46
2020/01/05;11.29
2020/01/06;10.02
2020/01/07;9.63
2020/01/08;6.75
2020/01/09;5.38
2020/01/10;6.96
2020/01/11;10.83
2020/01/12;8.83
2020/01/13;9.39
2020/01/14;5.75
2020/01/15;3.71
2020/01/16;9.21
2020/01/17;6.75
2020/01/18;10.46
2020/01/19;12.13
2020/01/20;10.88
2020/01/21;11.17
2020/01/22;9.25
2020/01/23;10.17
2020/01/24;13.83
2020/01/25;12.63
2020/01/26;13.25
2020/01/27;8.69
2020/01/28;10.08
2020/01/29;11.13
2020/01/30;8.13
2020/01/31;5.13
2020/02/01;4.58
2020/02/02;8.58
2020/02/03;7.83
2020/02/04;10.29
2020/02/05;12.00
2020/02/06;9.83
2020/02/07;9.58
2020/02/08;9.75
2020/02/09;5.54
2020/02/10;8.67
2020/02/11;11.13
2020/02/12;11.04
2020/02/13;12.33
2020/02/14;10.79
2020/02/15;6.83
2020/02/16;2.63
2020/02/17;7.25
2020/02/18;8.50
2020/02/19;9.63
2020/02/20;9.13
2020/02/21;9.08
2020/02/22;7.17
2020/02/23;9.71
2020/02/24;10.00
2020/02/25;8.88
2020/02/26;12.17
2020/02/27;11.79
2020/02/28;10.83
2020/02/29;7.71
2020/03/01;9.17
2020/03/02;8.50
2020/03/03;9.50
2020/03/04;11.17
2020/03/05;9.67
2020/03/06;10.21
2020/03/07;10.17
2020/03/08;6.67
2020/03/09;7.54
2020/03/10;6.79
2020/03/11;5.29
2020/03/12;6.79
2020/03/13;9.43
2020/03/14;11.30
2020/03/15;6.39
2020/03/16;6.00
2020/03/17;7.29
2020/03/18;4.83
2020/03/19;7.21
2020/03/20;8.42
2020/03/21;10.92
2020/03/22;11.42
2020/03/23;12.73
2020/03/24;11.02
2020/03/25;10.04
2020/03/26;9.04
2020/03/27;7.13
2020/03/28;8.25
2020/03/29;11.94
2020/03/30;13.04
2020/03/31;12.00
2020/04/01;10.42
2020/04/02;7.88
2020/04/03;9.63
2020/04/04;8.13
2020/04/05;4.75
2020/04/06;3.13
2020/04/07;3.40
2020/04/08;2.71
2020/04/09;4.81
2020/04/10;7.75
2020/04/11;5.33
2020/04/12;3.04
2020/04/13;8.21
2020/04/14;9.04
2020/04/15;5.67
2020/04/16;5.79
2020/04/17;5.33
2020/04/18;4.42
2020/04/19;5.54
2020/04/20;4.58
2020/04/21;3.38
2020/04/22;3.42
2020/04/23;2.46
2020/04/24;3.50
2020/04/25;4.38
2020/04/26;6.42
2020/04/27;3.71
2020/04/28;3.25
2020/04/29;5.13
2020/04/30;3.10
2020/05/01;5.08
2020/05/02;5.21
2020/05/03;5.04
2020/05/04;5.46
2020/05/05;5.46
2020/05/06;6.21
2020/05/07;4.79
2020/05/08;4.04
2020/05/09;2.08
2020/05/10;1.79
2020/05/11;7.04
2020/05/12;8.33
2020/05/13;7.29
2020/05/14;6.79
2020/05/15;7.17
2020/05/16;4.17
2020/05/17;3.33
2020/05/18;1.50
2020/05/19;1.67
2020/05/20;1.63
2020/05/21;1.00
2020/05/22;0.25
2020/05/23;2.04
2020/05/24;2.44
2020/05/25;3.04
2020/05/26;2.04
2020/05/27;1.83
2020/05/28;2.21
2020/05/29;1.71
2020/05/30;0.92
2020/05/31;0.88
2020/06/01;0.83
2020/06/02;0.29
2020/06/03;0.00
2020/06/04;0.79
2020/06/05;3.10
2020/06/06;3.11
2020/06/07;1.96
2020/06/08;1.50
2020/06/09;1.25
2020/06/10;0.54
2020/06/11;0.13
2020/06/12;0.00
2020/06/13;0.00
2020/06/14;0.00
2020/06/15;0.29
2020/06/16;0.08
2020/06/17;0.17
2020/06/18;0.00
2020/06/19;0.00
2020/06/20;0.13
2020/06/21;0.75
2020/06/22;0.00
2020/06/23;0.79
2020/06/24;0.04
2020/06/25;0.00
2020/06/26;0.00
2020/06/27;0.00
2020/06/28;0.04
2020/06/29;0.33
2020/06/30;0.29
2020/07/01;0.46
2020/07/02;0.33
2020/07/03;0.33
2020/07/04;0.00
2020/07/05;0.00
2020/07/06;1.00
2020/07/07;1.88
2020/07/08;1.33
2020/07/09;2.54
2020/07/10;1.71
2020/07/11;2.00
2020/07/12;1.58
2020/07/13;1.46
2020/07/14;0.33
2020/07/15;0.29
2020/07/16;0.17
2020/07/17;0.79
2020/07/18;0.08
2020/07/19;0.00
2020/07/20;0.17
2020/07/21;1.54
2020/07/22;1.42
2020/07/23;0.67
2020/07/24;0.00
2020/07/25;0.42
2020/07/26;0.04
2020/07/27;0.21
2020/07/28;0.13
2020/07/29;0.38
2020/07/30;1.17
2020/07/31;0.63
2020/08/01;0.00
2020/08/02;0.08
2020/08/03;0.79
2020/08/04;0.54
2020/08/05;0.08
2020/08/06;0.00
2020/08/07;0.00
2020/08/08;0.00
2020/08/09;0.00
2020/08/10;0.00
2020/08/11;0.00
2020/08/12;0.00
2020/08/13;0.00
2020/08/14;0.00
2020/08/15;0.00
2020/08/16;0.00
2020/08/17;0.00
2020/08/18;0.00
2020/08/19;0.00
2020/08/20;0.00
2020/08/21;0.00
2020/08/22;0.00
2020/08/23;0.00
2020/08/24;0.83
2020/08/25;0.92
2020/08/26;0.00
2020/08/27;0.38
2020/08/28;0.33
2020/08/29;0.88
2020/08/30;0.92
2020/08/31;0.33
2020/09/01;0.67
2020/09/02;1.79
2020/09/03;1.63
2020/09/04;0.17
2020/09/05;0.79
2020/09/06;2.21
2020/09/07;1.33
2020/09/08;0.37
2020/09/09;0.17
2020/09/10;1.54
2020/09/11;1.08
2020/09/12;1.89
2020/09/13;1.29
2020/09/14;0.29
2020/09/15;0.00
2020/09/16;0.38
2020/09/17;2.58
2020/09/18;3.38
2020/09/19;2.46
2020/09/20;2.17
2020/09/21;1.67
2020/09/22;2.04
2020/09/23;1.29
2020/09/24;0.29
2020/09/25;2.04
2020/09/26;3.63
2020/09/27;3.63
2020/09/28;2.88
2020/09/29;2.04
2020/09/30;1.04
2020/10/01;1.63
2020/10/02;1.17
2020/10/03;0.42
2020/10/04;2.67
2020/10/05;4.08
2020/10/06;2.75
2020/10/07;3.13
2020/10/08;3.29
2020/10/09;2.88
2020/10/10;6.17
2020/10/11;6.71
2020/10/12;7.38
2020/10/13;5.79
2020/10/14;5.13
2020/10/15;5.42
2020/10/16;6.75
2020/10/17;5.54
2020/10/18;5.71
2020/10/19;6.17
2020/10/20;5.96
2020/10/21;1.63
2020/10/22;0.79
2020/10/23;3.50
2020/10/24;1.96
2020/10/25;1.67
2020/10/26;4.79
2020/10/27;5.00
2020/10/28;4.17
2020/10/29;5.42
2020/10/30;2.08
2020/10/31;1.38
2020/11/01;1.71
2020/11/02;0.38
2020/11/03;5.21
2020/11/04;7.08
2020/11/05;7.17
2020/11/06;4.79
2020/11/07;6.60
2020/11/08;7.21
2020/11/09;9.13
2020/11/10;9.83
2020/11/11;9.04
2020/11/12;6.88
2020/11/13;6.17
2020/11/14;3.67
2020/11/15;1.63
2020/11/16;5.13
2020/11/17;4.54
2020/11/18;3.75
2020/11/19;6.42
2020/11/20;11.13
2020/11/21;9.25
2020/11/22;6.79
2020/11/23;8.96
2020/11/24;9.17
2020/11/25;11.42
2020/11/26;8.17
2020/11/27;11.42
2020/11/28;13.25
2020/11/29;12.23
2020/11/30;12.71
2020/12/01;11.04
2020/12/02;12.25
2020/12/03;13.71
2020/12/04;13.00
2020/12/05;12.58
2020/12/06;10.71
2020/12/07;9.58
2020/12/08;10.08
2020/12/09;12.08
2020/12/10;12.83
2020/12/11;13.42
2020/12/12;12.46
2020/12/13;11.58
2020/12/14;8.42
2020/12/15;7.42
2020/12/16;7.21
2020/12/17;6.67
2020/12/18;8.75
2020/12/19;8.67
2020/12/20;7.67
2020/12/21;8.29
2020/12/22;6.58
2020/12/23;10.38
2020/12/24;11.00
2020/12/25;14.44
2020/12/26;13.08
2020/12/27;11.00
2020/12/28;11.31
2020/12/29;12.38
2020/12/30;11.22

Setup

We have a wide variety of customers, and our API is used by them with a wide variety of systems: from professional EnMS platforms to in-house programming to Excel.

Of course, we can also provide technical support during the initial setup.

Test our API

You can also test our API service without any obligation!

Book one of our API subscriptions and test the full range of features. If you find that the service does not meet your expectations within 30 days, you can cancel the subscription without giving any reason and get the full purchase price back.

Book a degree day subscription now with 30-day money back guarantee!