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.
Choose a supported forecast model using the dropdown. The model is part of the URL path; initialization_time remains an optional query parameter. Results come from the latest completed degree-day calculation for that model when no initialization time is specified.
| Name | Type | Description |
|---|---|---|
| initialization_time Optional | string (ISO 8601) | The initialization time for the forecast. Default: initialization time of the latest completed degree-day calculation |
| Name | Type | Description |
|---|---|---|
| initialization_time Optional | string (ISO 8601 or YYYYMMDDHH) | The initialization time for the forecast. Default: initialization time of the latest completed degree-day calculation |
| -m , --model Required | string | Weather model to use. Allowed: wm-6, wm-6-3km, wm-4.5-ens-mean, ecmwf-det, ecmwf-ens, aifs, gfs, gefs |
| -o , --output Optional | string | Output file path. Supports .csv and .json. If omitted, prints to console. |
| Name | Type | Description |
|---|---|---|
| initialization_time Optional | str (ISO 8601 or YYYYMMDDHH) | The initialization time for the forecast. Default: initialization time of the latest completed degree-day calculation |
| model Required | str | Weather model to use. Allowed: wm-6, wm-6-3km, wm-4.5-ens-mean, ecmwf-det, ecmwf-ens, aifs, gfs, gefs |
| output_file Optional | str | Path to save the response data. Supports .csv and .json. |
| print_response Optional | bool | If true, prints the response data. Default: false |
Returns population weighted heating-degree-days (HDD) data for all 50 US states and the list of forecast dates.
| Name | Type | Description |
|---|---|---|
| hdd | object | HDD values keyed by local calendar date; each date maps to a state-to-value object. |
| <date> | object | Keyed by state name, with HDD values for that date. |
| <state> | number | null | HDD value for the state and local date; null when forecast data is unavailable. Unit: °F degree days |
| dates | string[] (YYYY-MM-DD) | Forecast dates, based on local time within each state. Boundary dates can have only null values when local forecast data is unavailable. |
| metadata | object | Forecast calculation metadata. |
| model | string | Model name. |
| subset | string | Forecast subset identifier. |
| initialization_time | string (ISO 8601) | Initialization time of the calculation. |