Degree Day Weather API

Degree days are a standardized method to calculate the total heat or warmth a location has experienced. They are used in agriculture and gardening to estimate the growth stages of plants and phenology. Degree days can be also be used in building construction and maintenance as a way to estimate the heating and cooling needs of a building.

The Degree Days Weather API is available in the Corporate plan. To sign up, visit our Weather Data Services page.

For more detailed information on degree days and their usage, see our degree days information.

For sample code using the degree day API, please see the code samples in our Github repository.

The Timeline Weather API also supports basic degree day information. For more information, please see the API documentation.

Degree Day Calculations

Simple Average Calculation

By default we use a simple average calculation. The simple average degree days for a particular day is calculated using the following formula:

Mean temperature=(maximum temperature+minimum temperature)/2
Degree days=Mean Temperature-Base Temperature


The base temperature can differ depending on the use case. For example, the growing degree days for growing corn often use a base temperature of 50F. For cooling degree days (sometimes abbreviated CDD) , a base temperature of 65F commonly used.

In some application, such as growing degree days (often abbreviated GDD) , temperatures above a certain value are considered the same as a fixed maximum. This may be because a plant will grow faster with warmer temperatures but after the temperature increases too much, no additional growth benefits will be seen. This value is the maximum threshold – any temperature above the maximum temperature threshold will be treated as the maximum threshold temperature.

Finally, heating degree days (HDD) are calculated as the inverse of growing degree days. There are more heating degree days for days with colder mean temperatures.

 Heating Degree days=Base Temperature-Mean Temperature

The base temperature for heating degree days is typically 65F. Therefore heating degree days increases as the mean daily temperature drops.

Sine and triangle calculations

In addition to the simple average, the degree day API also supports sine and triangle calculation methods for degree days. These can be augmented to their double sine and double triangle methods to combine the low temperature for the current and following day for higher accuracy.

Degree Day API Reference

The degree day API offers the following parameters:

location – A single address or latitude, longitude value indicating the location for which you would like degree day information

unitGroup – The system of units used for the output data.
Supported values are us, uk, metric, and base. See Unit groups and measurement units for more information.

degreeDayStats – Whether or not to include the maximum, minimum and mean degree day values (true or false)

degreeDayTempFix – The temperature at which to start the degree day season if no season start and end dates are specified. For example, if the fix temperature is 32F (OC), then the cumulative degree days will reset to zero on the last 32F temperature of the winter. This defines the growing season for growing degree days. Defaults to 32F/0C if not specified and no start and end dates are specified

degreeDayStartDate – Fixes the start of the degree day season based on fixed dates of the format yyyy-M-d (eg 1990-3-1 for 1st March). Default=not specified.

degreeDayEndDate – Fixes the end of the degree day season based on fixed dates of the format yyyy-M-d (eg 1990-3-1 for 1st March). Default=not specified.

degreeDayTempMaxThreshold – Defines the maximum temperature that is considered for the calculation. Any temperature above this temperature will be set to the maximum threshold temperature. Default value=not set.

degreeDayTempBase – The degree day base temperature. Default value is set to 10C/50F

degreeDayInverse – Calculate the inverse degree days so colder temperatures contribute more degree days. Used for heating degree days. Default=false.

minYear – When calculating statistics, the minimum year to include in the statistics. (default current year minus 30 years)

degreeDayFocusYear – The year for which to calculate the main degree day value. (default = current year)

degreeDayMethod (beta) – The method used for calculating the degree days. Values include average, sine, doublesine, triangle and doubletriangle. Default value is set to average.

Result format

The degree output is available as a CSV or JSON output with the following structure:

Date – the date of the information for the focus year

mint – the minimum temperature on that day

maxt – the maximum temperature on that day

degreedays – the number of degree days for that day only

cumulativedegreedays – the number of degree days from the start of the season up to and including the current day

mincumulativedegreedays – when statistics are included, the minimum cumulative degree days that occurred by this day on any year

maxcumulativedegreedays – when statistics are included, the mean cumulative degree days that occurred by this day.

meancumulativedegreedays – when statistics are included, the maximum cumulative degree days that occurred by this day on any year

Example output:

datetime,mint,maxt,degreedays,cumulativedegreedays,mincumulativedegreedays,maxcumulativedegreedays,meancumulativedegreedays
 "03/28/2020",,,,,,0,0
 "03/29/2020",,,,,,4,6
 "03/30/2020",,,,,,5,8
 "03/31/2020",,,,,,16,13
 "04/01/2020",,,,,,25,18
 "04/02/2020",,,,,,39,20
 "04/03/2020",,,,,,53,31
 "04/04/2020",,,,,,68,30
 "04/05/2020",,,,,,87,31
 "04/06/2020",,,,,,115,35
 "04/07/2020",,,,,,143,42
 "04/08/2020",,,,,,163,44
 "04/09/2020",,,,,,165,43
 "04/10/2020",,,,,,169,50
 "04/11/2020",,,,,,177,57
 "04/12/2020",,,,,,189,60
 "04/13/2020",,,,,,189,62
 "04/14/2020",,,,,,192,65
 "04/15/2020",,,,,,201,71
 "04/16/2020",,,,,3,221,75
 "04/17/2020",,,,,3,228,78
 "04/18/2020",,,,,3,228,86
 "04/19/2020",,,,,3,231,90
 "04/20/2020",48.1,62.9,6,6,3,237,93
 "04/21/2020",46,65.8,6,11,3,239,101
 "04/22/2020",37.1,61,0,11,3,250,106
 "04/23/2020",42.1,57.8,0,11,3,260,114
 "04/24/2020",51.2,56.7,4,15,5,263,122
 "04/25/2020",42.1,61.1,2,17,6,279,126
 "04/26/2020",47.7,55.7,2,19,12,288,136
 "04/27/2020",42.4,57.6,0,19,14,294,145
 "04/28/2020",39.7,52.1,0,19,19,294,153
 "04/29/2020",41,73.9,7,26,23,299,161
 "04/30/2020",54.9,66.8,11,37,32,313,170
 ...

Usage Examples

Basic request

https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/weatherdata/degreedays?&unitGroup=us&degreeDayStats=false&location=Herndon,VA&key=YOUR_API_KEY

This will request the degree days for the requested location using the default base temperature of 50F/10C and the season will start on the day after the last day with below freezing temperatures.

Sine calculation method request

https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/weatherdata/degreedays?&unitGroup=us&degreeDayStats=false&location=Herndon,VA&degreeDayMethod=sine&key=YOUR_API_KEY

The “degreeDayMethod” parameter is added to change the default calculation method.

Corn Growing degree days request

https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/weatherdata/degreedays?&unitGroup=us&degreeDayStats=false&degreeDayTempFix=32&degreeDayTempMaxThreshold= 86&degreeDayTempBase=50&shortColumnNames=true&location=Herndon,VA&key=YOUR_API_KEY

Similar to the above, this defines the base growing temperature of 50F using the “degreeDayTempBase” parameter. The maximum growing temperature of 86F is set using the “degreeDayTempMaxThreshold” parameter.

Heating Degree Days

 https://weather.visualcrossing.com /VisualCrossingWebServices/rest/services/weatherdata/degreedays?&unitGroup=us&degreeDayStats=false&degreeDayStartDate=2020-7-1&degreeDayEndDate=2020-6-30&degreeDayTempBase=65&degreeDayInverse=true&degreeDayFocusYear=2019&shortColumnNames=true&location=Herndon,VA&key=YOUR_API_KEY 

In this case, the degreeDayInverse parameter has been set to true. This means that the API will calculate heating degree days. In addition, to define the heating season to cross a year boundary the year, we set explicit start and end dates.