API Documentation

Get to know the technical functions of the Energy Data programming interface and how you can integrate the API smoothly into your systems.

The Energy Data API

Our database and the calculation of Heating Degree Days and Cooling Degree Days are available via a CSV 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).

The Data Query

If you already purchased valid API key and want to skip the following technical documentation, click here:

The following will describe the technical structure of our API. The URL structure of a data query is:
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
      • monthly – results aggregated by months; breakdown=monthly
      • yearly – results aggregated by years; breakdown=yearly
      API Key (key=)

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

      • e.g. key=98a474de-c565-452e-ba8b-580b696b3d45

      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=5yxCbgf54lgprejuW8rA

      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

      Unsere API wird von Kunden mit den unterschiedlichsten Systemen genutzt: von professionellen EnMS-Plattformen über Eigenprogrammierung bis zu Excel. 

      Selbstverständlich können wir Sie bei der Ersteinrichtung auch technisch unterstützen.

      API testen

      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!