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 API is available in the Visual Crossing Weather Corporate plan. If you would like to evaluate the degrees API, our free trial includes full access. To sign up, visit our Weather Data Services page.

The degree days for a particular day is calculated using the follow 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.

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.

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)

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=true&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.

Corn Growing degree days request

https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/weatherdata/degreedays?&unitGroup=us&degreeDayStats=true&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 and the maximum growing temperature of 86F

Heating Degree Days

 https://weather.visualcrossing.com /VisualCrossingWebServices/rest/services/weatherdata/degreedays?&unitGroup=us&degreeDayStats=true&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.

Leave a Reply

Your email address will not be published. Required fields are marked *