API Documentation

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

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. 

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
    • weekly – result aggregated by week; breakdown=weekly + week_start=[weekday]
    • 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=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!

    Degree-Days-as-a-Service

    save more than 10% on annual plans

    Lite

    The Starter Package

    39 € /mth.

    Tools included:
    • RDegree Day Calculator PRO
      Access to our easy-to-use web-based Degree Day Calculator.
    • REnergy Normalizer
      Normalize your energy data directly in your browser. No more complex calculations and spending hours on an Excel data sheet.
    • RAPI
      Connect your energy management software, database, or Excel sheet to our database and automatically fetch the latest Degree Days via API.
    Data included:
    • RHeating Degree Days (HDD)
    • R"Room Heating Degree Days" (DD)
    • RCooling Degree Days (CDD)
    • Rup to 10 locations
    • Rmin. 10 years of historical data
    • Rup to 100 requests per hour

    learn more

    • R30 days money back guarentee
      Test our service risk-free for 30 days. If you are not satisfied, we will refund 100% of your payment.

    Professional

    For high Data Demands

    89 € /mth.

    Tools included:
    • RDegree Day Calculator PRO
      Access to our easy-to-use web-based Degree Day Calculator.
    • REnergy Normalizer
      Normalize your energy data directly in your browser. No more complex calculations and spending hours on an Excel data sheet.
    • RAPI
      Connect your energy management software, database, or Excel sheet to our database and automatically fetch the latest Degree Days via API.
    Data included:
    • RHeating Degree Days (HDD)
    • R"Room Heating Degree Days" (DD)
    • RCooling Degree Days (CDD)
    • Rup to 25 locations
    • Rmin. 10 years of historical data
    • Rup to 1,000 requests per hour

    learn more

    • R30 days money back guarentee
      Test our service risk-free for 30 days. If you are not satisfied, we will refund 100% of your payment.

    Enterprise

    All Features

    149 € /mth.

    Tools included:
    • RDegree Day Calculator PRO
      Access to our easy-to-use web-based Degree Day Calculator.
    • REnergy Normalizer
      Normalize your energy data directly in your browser. No more complex calculations and spending hours on an Excel data sheet.
    • RAPI
      Connect your energy management software, database, or Excel sheet to our database and automatically fetch the latest Degree Days via API.
    Data included:
    • RHeating Degree Days (HDD)
    • R"Room Heating Degree Days" (DD)
    • RCooling Degree Days (CDD)
    • Rover 23,000 locations
    • Rmin. 10 years of historical data
    • Rup to 4,000 requests per hour

    learn more

    • R30 days money back guarentee
      Test our service risk-free for 30 days. If you are not satisfied, we will refund 100% of your payment.

    Do you need a higher hourly rate limit (request units per hour)?