This endpoint provides Population Weighted Heating Degree Days (HDD) for all 50 US states, using all available forecast hours. HDD measures how cold a day is relative to a 65°F base, weighted by population density to better reflect energy demand.
A model parameter can be provided to specify which weather model’s forecast HDDs to retrieve. You can find a list of available models here.
If no model is provided, the latest available model is used by default.
| Name | Description | Format |
|---|---|---|
| initialization_time Required | The initialization time for the forecast. Uses only date and hour; minutes and seconds are discarded. | ISO 8601, YYYYMMDDHH, or YYYY-MM-DDTHH |
| ens_member Optional | The ensemble member to get HDD for. | mean or 0-23 |
| Name | Description | Format |
|---|---|---|
| initialization_time Required | The initialization time for the forecast. Uses only date and hour; minutes and seconds are discarded. | ISO 8601, YYYYMMDDHH, or YYYY-MM-DDTHH |
| ens_member Optional | The ensemble member to get HDD for. | mean or 0-23 |
| Name | Description | Format |
|---|---|---|
| initialization_time Required | The initialization time for the forecast. Uses only date and hour; minutes and seconds are discarded. | ISO 8601, YYYYMMDDHH, or YYYY-MM-DDTHH |
| Name | Description | Format |
|---|---|---|
| initialization_time Required | The initialization time for the forecast. Uses only date and hour; minutes and seconds are discarded. | ISO 8601, YYYYMMDDHH, or YYYY-MM-DDTHH |
| ens_member Optional | The ensemble member to get HDD for. | mean or 0-23 |
| Name | Description | Format |
|---|---|---|
| initialization_time Required | The initialization time for the forecast. Uses only date and hour; minutes and seconds are discarded. | ISO 8601, YYYYMMDDHH, or YYYY-MM-DDTHH |
| Name | Description | Format |
|---|---|---|
| initialization_time Required | The initialization time for the forecast. Uses only date and hour; minutes and seconds are discarded. | ISO 8601, YYYYMMDDHH, or YYYY-MM-DDTHH |
| Name | Description | Format |
|---|---|---|
| initialization_time Required | The initialization time for the forecast. Uses only date and hour; minutes and seconds are discarded. | ISO 8601, YYYYMMDDHH, or YYYY-MM-DDTHH |
| Name | Description | Format |
|---|---|---|
| initialization_time Required | The initialization time for the forecast. Uses only date and hour; minutes and seconds are discarded. | ISO 8601, YYYYMMDDHH, or YYYY-MM-DDTHH |
| Name | Description | Format |
|---|---|---|
| initialization_time Required | The initialization time for the forecast. Uses only date and hour; minutes and seconds are discarded. | ISO 8601, YYYYMMDDHH, or YYYY-MM-DDTHH |
| Name | Description |
|---|---|
| initialization_time Required | The initialization time for the forecast. Formats: YYYYMMDDHH, YYYY-MM-DDTHH, YYYY-MM-DDTHH:mm:ss. Uses only date and hour; minutes and seconds are discarded. |
| -e --ens-member Optional | The ensemble member to get HDD for. Can be "mean" or a number between 0 and 23. |
| -m --model | Set to wm5c . |
| -o, --output Optional | Output file path. Supports .csv and .json. If omitted, prints to console. CSV will have states as rows and dates as columns. |
| Name | Description |
|---|---|
| initialization_time Required | The initialization time for the forecast. Formats: YYYYMMDDHH, YYYY-MM-DDTHH, YYYY-MM-DDTHH:mm:ss. Uses only date and hour; minutes and seconds are discarded. |
| -e --ens-member Optional | The ensemble member to get HDD for. Can be "mean" or a number between 0 and 23. |
| -m --model | Set to wm4.5-ens . |
| -o, --output Optional | Output file path. Supports .csv and .json. If omitted, prints to console. CSV will have states as rows and dates as columns. |
| Name | Description |
|---|---|
| initialization_time Required | The initialization time for the forecast. Formats: YYYYMMDDHH, YYYY-MM-DDTHH, YYYY-MM-DDTHH:mm:ss. Uses only date and hour; minutes and seconds are discarded. |
| -m --model | Set to wm4 . |
| -o, --output Optional | Output file path. Supports .csv and .json. If omitted, prints to console. CSV will have states as rows and dates as columns. |
| Name | Description |
|---|---|
| initialization_time Required | The initialization time for the forecast. Formats: YYYYMMDDHH, YYYY-MM-DDTHH, YYYY-MM-DDTHH:mm:ss. Uses only date and hour; minutes and seconds are discarded. |
| -e --ens-member Optional | The ensemble member to get HDD for. Can be "mean" or a number between 0 and 23. |
| -m --model | Set to wm4-ens . |
| -o, --output Optional | Output file path. Supports .csv and .json. If omitted, prints to console. CSV will have states as rows and dates as columns. |
| Name | Description |
|---|---|
| initialization_time Required | The initialization time for the forecast. Formats: YYYYMMDDHH, YYYY-MM-DDTHH, YYYY-MM-DDTHH:mm:ss. Uses only date and hour; minutes and seconds are discarded. |
| -m --model | Set to wm4-intra . |
| -o, --output Optional | Output file path. Supports .csv and .json. If omitted, prints to console. CSV will have states as rows and dates as columns. |
| Name | Description |
|---|---|
| initialization_time Required | The initialization time for the forecast. Formats: YYYYMMDDHH, YYYY-MM-DDTHH, YYYY-MM-DDTHH:mm:ss. Uses only date and hour; minutes and seconds are discarded. |
| -m --model | Set to ecmwf-det . |
| -o, --output Optional | Output file path. Supports .csv and .json. If omitted, prints to console. |
| Name | Description |
|---|---|
| initialization_time Required | The initialization time for the forecast. Formats: YYYYMMDDHH, YYYY-MM-DDTHH, YYYY-MM-DDTHH:mm:ss. |
| -m --model | Set to ecmwf-ens . |
| -o, --output Optional | Output file path. Supports .csv and .json. |
| Name | Description |
|---|---|
| initialization_time Required | The initialization time for the forecast. |
| -m --model | Set to aifs . |
| -o, --output Optional | Output file path. Supports .csv and .json. |
| Name | Description |
|---|---|
| initialization_time Required | The initialization time for the forecast. |
| -m --model | Set to gfs . |
| -o, --output Optional | Output file path. Supports .csv and .json. |
| Name | Type | Description |
|---|---|---|
| initialization_time Required | str | The initialization time for the forecast. Formats: YYYYMMDDHH, YYYY-MM-DDTHH, YYYY-MM-DDTHH:mm:ss. Uses only date and hour; minutes and seconds are discarded. |
| ens_member Optional | str | The ensemble member to use. Can be "mean" or a number between 0 and 23. |
| model | str | Set to wm5c . |
| output_file Optional | str | Path to save the response data. Supports .csv and .json. CSV will have states as rows and dates as columns. |
| print_response Optional | bool | Whether to print the response data to console. Defaults to False. |
| Name | Type | Description |
|---|---|---|
| initialization_time Required | str | The initialization time for the forecast. Formats: YYYYMMDDHH, YYYY-MM-DDTHH, YYYY-MM-DDTHH:mm:ss. Uses only date and hour; minutes and seconds are discarded. |
| ens_member Optional | str | The ensemble member to use. Can be "mean" or a number between 1 and 25 as a string. |
| model | str | Set to wm4.5-ens . |
| output_file Optional | str | Path to save the response data. Supports .csv and .json. CSV will have states as rows and dates as columns. |
| print_response Optional | bool | Whether to print the response data to console. Defaults to False. |
| Name | Type | Description |
|---|---|---|
| initialization_time Required | str | The initialization time for the forecast. Formats: YYYYMMDDHH, YYYY-MM-DDTHH, YYYY-MM-DDTHH:mm:ss. Uses only date and hour; minutes and seconds are discarded. |
| model | str | Set to wm4 . |
| output_file Optional | str | Path to save the response data. Supports .csv and .json. CSV will have states as rows and dates as columns. |
| print_response Optional | bool | Whether to print the response data to console. Defaults to False. |
| Name | Type | Description |
|---|---|---|
| initialization_time Required | str | The initialization time for the forecast. Formats: YYYYMMDDHH, YYYY-MM-DDTHH, YYYY-MM-DDTHH:mm:ss. Uses only date and hour; minutes and seconds are discarded. |
| ens_member Optional | str | The ensemble member to use. Can be "mean" or a number between 1 and 25 as a string. |
| model | str | Set to wm4-ens . |
| output_file Optional | str | Path to save the response data. Supports .csv and .json. CSV will have states as rows and dates as columns. |
| print_response Optional | bool | Whether to print the response data to console. Defaults to False. |
| Name | Type | Description |
|---|---|---|
| initialization_time Required | str | The initialization time for the forecast. Formats: YYYYMMDDHH, YYYY-MM-DDTHH, YYYY-MM-DDTHH:mm:ss. Uses only date and hour; minutes and seconds are discarded. |
| model | str | Set to wm4-intra . |
| output_file Optional | str | Path to save the response data. Supports .csv and .json. CSV will have states as rows and dates as columns. |
| print_response Optional | bool | Whether to print the response data to console. Defaults to False. |
| Name | Type | Description |
|---|---|---|
| initialization_time Required | str | The initialization time for the forecast. |
| model | str | Set to ecmwf-det . |
| output_file Optional | str | Path to save the response data. Supports .csv and .json. |
| print_response Optional | bool | Whether to print the response data to console. Defaults to False. |
| Name | Type | Description |
|---|---|---|
| initialization_time Required | str | The initialization time for the forecast. |
| model | str | Set to ecmwf-ens . |
| output_file Optional | str | Path to save the response data. Supports .csv and .json. |
| print_response Optional | bool | Whether to print the response data to console. Defaults to False. |
| Name | Type | Description |
|---|---|---|
| initialization_time Required | str | The initialization time for the forecast. |
| model | str | Set to aifs . |
| output_file Optional | str | Path to save the response data. Supports .csv and .json. |
| print_response Optional | bool | Whether to print the response data to console. Defaults to False. |
| Name | Type | Description |
|---|---|---|
| initialization_time Required | str | The initialization time for the forecast. |
| model | str | Set to gfs . |
| output_file Optional | str | Path to save the response data. Supports .csv and .json. |
| print_response Optional | bool | Whether to print the response data to console. Defaults to False. |
Returns population weighted heating-degree-days (HDD) data for all 50 US states and the list of forecast dates.
| Name | Description | Format |
|---|---|---|
| hdd | HDD values keyed by forecast date_string; each date maps to a state-to-value object | object |
| date_string | Object keyed by state_name with HDD values for that date | object |
| state_name | HDD value for the given state on that date_string | floating point number |
| dates | Array of forecast dates in YYYY-MM-DD format | YYYY-MM-DD |
| date | Forecast date in YYYY-MM-DD format | - |