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. 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):

  • Degree Day API High / Advanced plan(s): 1 year of data per call (Example: 2017-01-01 to 2018-01-01)
  • Degree Day API Low plan: 1 day of data per call (Example: 2018-05-01 to 2018-05-02)
  • Other plan(s): No access

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 (Celcius, m/s, mm)
  • S - Scientific (Kelvin, m/s, mm)
  • I - Fahrenheit (F, mph, in)
tp=[time_period] (optional - Time period of each timestamp, default = daily)
  • hourly - Aggregate in hourly time steps (limit 7 days/168 hours)
  • daily - [DEFAULT] Aggregate in Daily time steps
  • monthly - Aggregate in Monthly time steps
threshold=[degrees]
callback=[function] (optional: JSON-P callback)

API Endpoints

Description Required Parameters Example(s)
Get data by lat/lon lat, lon, start_date, end_date &lat=38.123&lon=-78.543&start_date=2019-04-16&end_date=2019-04-17
Get data by city name city, state(optional), country (optional), start_date, end_date &city=Raleigh,NC&start_date=2019-04-16&end_date=2019-04-17
Get data by postal code postal_code, country (optional), start_date, end_date &postal_code=27601&country=US&start_date=2019-04-16&end_date=2019-04-17
Get data by city id city_id, start_date, end_date &city_id=8953360&start_date=2019-04-16&end_date=2019-04-17
Get data by ICAO or station id station, start_date, end_date &station=KRDU&start_date=2019-04-16&end_date=2019-04-17

Example Request:

https://api.weatherbit.io/v2.0/history/energy?lat=38.0&lon=-78.0&start_date=2019-04-16&end_date=2019-04-17&threshold=63&units=I&key=API_KEY&tp=daily

Example Response (JSON):


        {  
           "threshold_units":"F",
           "timezone":"America\/New_York",
           "threshold_value":"63",
           "state_code":"VA",
           "country_code":"US",
           "city_name":"Louisa",
           "data":[  
              {  
                 "date":"2019-03-04",
                 "timestamp_utc":"2019-03-04T17:00:00",
                 "timestamp_local":"2019-03-04T12:00:00",
                 "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,
                 "sun_hours":4.7,
                 "clouds":6
              },
              {  
                 "date":"2019-03-04",
                 "timestamp_utc":"2019-03-04T18:00:00",
                 "timestamp_local":"2019-03-04T13:00:00",
                 "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,
                 "sun_hours":1.5,
                 "clouds":100
                 
              }
           ],
           "start_date":"2019-03-04",
           "end_date":"2019-03-06",
           "station_id":"723114-03715",
           "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: Source station ID.
  • 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.
    • 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 Celcius).
    • temp_wetbulb: Average wet bulb temperature over period (default Celcius).
    • rh: Average relative humidity over period (%).
    • dewpt: Average dew point over period (default Celcius).
    • 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]
    • sun_hours: Average daily peak sun hours (where hourly GHI > 1000 W/m^2) over period.
  • ]