Historical Energy Weather API (Degree Days API)
This API returns historical weather data specific to the energy industry from our network of over 120,000 stations as well as radar/satellite, and the ERA 5 atmospheric re-analysis. With this API, you can retrieve cooling or heating degree day data. Additionally, you can retrieve other valuable information like total sun hours, precipitation, snowfall, and more!
Be sure to check out our blog to read about the methodology for calculating degree days.
This API is available to the following plans (See: pricing):
- Business plan
- Enterprise plan
The following per API request limitations apply (See: pricing):
- Trial plan: 1 day of data per API request.
- *Business / Enterprise plans: 5 days of data per API request.
- Other plan(s): No access.
*For convenience, up to 1 year of data can be requested per API request. However, requests that exceed 5 days will count as multiple requests against the plan daily quota. Example: 364 days = 73 requests, 30 days = 6 requests, etc.
All parameters should be supplied to the Weather API as query string parameters.
Base URL
Request Parameters
key- Your API Key.
M- [DEFAULT] Metric (Celsius, m/s, mm)S- Scientific (Kelvin, m/s, mm)I- Fahrenheit (F, mph, in)
utc- [DEFAULT] Assumes UTC for start_date, end_datelocal- Assumes LOCAL time for start_date, end_date
hourly- Aggregate in hourly time stepsdaily- [DEFAULT] Aggregate in Daily time stepsmonthly- Aggregate in Monthly time steps
API Endpoints
| Description | Required Parameters | Example(s) |
|---|---|---|
| Get data by lat/lon (Recommended) | lat, lon, start_date, end_date | &lat=38.123&lon=-78.543&start_date=2024-11-17&end_date=2024-11-18 |
| Get data by city name | city, state(optional), country (optional), start_date, end_date | &city=Raleigh,NC&start_date=2024-11-17&end_date=2024-11-18 |
| Get data by postal code | postal_code, country (optional), start_date, end_date | &postal_code=27601&country=US&start_date=2024-11-17&end_date=2024-11-18 |
| Get data by city id | city_id, start_date, end_date | &city_id=8953360&start_date=2024-11-17&end_date=2024-11-18 |
| Get data by ICAO or station id | station, start_date, end_date | &station=KRDU&start_date=2024-11-17&end_date=2024-11-18 |
Example Request:
https://api.weatherbit.io/v2.0/history/energy?lat=38.0&lon=-78.0&start_date=2024-11-17&end_date=2024-11-18&threshold=63&units=I&key=API_KEY&tp=dailyExample Response (JSON):
{
"threshold_units":"F",
"timezone":"America\/New_York",
"threshold_value":"63",
"state_code":"VA",
"country_code":"US",
"city_name":"Louisa",
"lat":38.0,
"lon":-78.0,
"data":[
{
"date":"2019-03-04",
"timestamp_utc":"2019-03-04T17:00:00",
"timestamp_local":"2019-03-04T12:00:00",
"revision_status":"final",
"dewpt":33.4,
"snow":0,
"max_wind_spd":8.1,
"hdd":13,
"cdd":0,
"rh":86,
"wind_spd":4.7,
"dhi":194.8,
"wind_dir":166,
"precip":0,
"temp":44.9,
"temp_wetbulb":44.3,
"t_dni":1245,
"t_dhi":400,
"t_ghi":3000,
"t_solar_rad":1500,
"sun_hours":4.7,
"clouds":6
},
{
"date":"2019-03-04",
"timestamp_utc":"2019-03-04T18:00:00",
"timestamp_local":"2019-03-04T13:00:00",
"revision_status":"final",
"dewpt":45.1,
"snow":0,
"max_wind_spd":9.2,
"hdd":17.3,
"cdd":0,
"rh":86,
"wind_spd":5.1,
"dhi":61.7,
"wind_dir":52,
"precip":0.6,
"temp":44.5,
"temp_wetbulb":44.2,
"t_dni":1245,
"t_dhi":400,
"t_ghi":3000,
"t_solar_rad":1500,
"sun_hours":1.5,
"clouds":100
}
],
"start_date":"2019-03-04",
"end_date":"2019-03-06",
"station_id":"723114-03715",
"sources"["723114-03715", "imerg","sat"],
"count":48,
"city_id":4770766
}
Field Decriptions:
count:Count of returned objects.start_date:Start date (YYYY-MM-DD).end_date:End date (YYYY-MM-DD).threshold_units:Degree Day threshold units (F/C/K).threshold_value:Degree Day threshold value in degrees.lat:Latitude (Degrees).lon:Longitude (Degrees).timezone:Local IANA Timezone.city_name:City name.city_id:City ID.station_id:Nearest station ID. [DEPRECATED]sources:List of data sources used in response.country_code:Country abbreviation.state_code:State abbreviation/code.data: [date:Date (YYYY-MM-DD).timestamp_local:Timestamp at local time.timestamp_utc:Timestamp at UTC time.revision_statusData revision status - interim (subject to revisions) or final.wind_spd:Average wind speed over period (Default m/s).wind_dir:Average wind direction over period (degrees).max_wind_spd:Maximum wind gust over period (Default m/s).max_wind_dir:Maximum wind gust direction (degrees).cdd:Total number of cooling degree days relative to threshold temperature.hdd:Total number of heating degree days relative to threshold temperature.temp:Average temperature over period (default Celsius).temp_wetbulb:Average wet bulb temperature over period (default Celsius).rh:Average relative humidity over period (%).dewpt:Average dew point over period (default Celsius).clouds:[Satellite based] average cloud coverage over period (%).precip:Accumulated liquid equivalent precipitation over period (default mm).snow:Accumulated snowfall over period (default mm).t_dni:Total direct normal irradiance (W/M^2) [Clear Sky]t_ghi:Total global horizontal irradiance (W/M^2) [Clear Sky]t_dhi:Total diffuse horizontal irradiance (W/M^2) [Clear Sky]t_solar_rad:Total solar radiation (W/M^2)sun_hours:Total peak sun hours over period.]