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.
The following per API call limitations apply (See: pricing):
- Trial plan: 7 days of data per API call.
- *Pro / Business / Enterprise plans: 7 days of data per API call.
- Other plan(s): No access.
*For convenience, up to 1 year of data can be requested per API call. However, requests that exceed 7 days will count as multiple requests against the plan daily quota. Example: 1 year = 52 requests, 6 months = 26 requests, etc.
All parameters should be supplied to the Weather API as query string parameters.
Base URL
HTTP: http://api.weatherbit.io/v2.0/history/energy
HTTPS: https://api.weatherbit.io/v2.0/history/energy
Supported Methods: GET
Request Parameters
key=[key] (REQUIRED)
key- Your API Key.
start_date=[YYYY-MM-DD] (REQUIRED)
end_date=[YYYY-MM-DD] (REQUIRED)
units=[units](optional)
M- [DEFAULT] Metric (Celsius, m/s, mm)S- Scientific (Kelvin, m/s, mm)I- Fahrenheit (F, mph, in)
tz=[utc OR local](optional)
utc- [DEFAULT] Assumes UTC for start_date, end_datelocal- Assumes LOCAL time for start_date, end_date
tp=[time_period] (optional - Time period of each timestamp, default = daily)
hourly- Aggregate in hourly time stepsdaily- [DEFAULT] Aggregate in Daily time stepsmonthly- Aggregate in Monthly time steps
threshold=[degrees]
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=2023-12-04&end_date=2023-12-05 |
| Get data by city name | city, state(optional), country (optional), start_date, end_date | &city=Raleigh,NC&start_date=2023-12-04&end_date=2023-12-05 |
| Get data by postal code | postal_code, country (optional), start_date, end_date | &postal_code=27601&country=US&start_date=2023-12-04&end_date=2023-12-05 |
| Get data by city id | city_id, start_date, end_date | &city_id=8953360&start_date=2023-12-04&end_date=2023-12-05 |
| Get data by ICAO or station id | station, start_date, end_date | &station=KRDU&start_date=2023-12-04&end_date=2023-12-05 |
Example Request:
https://api.weatherbit.io/v2.0/history/energy?lat=38.0&lon=-78.0&start_date=2023-12-04&end_date=2023-12-05&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.]