Historical Energy Weather API (Degree Days API)

This API returns historical weather data specific to the energy industry from our network of over 38,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)
  • 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=2018-12-11&end_date=2018-12-12
Get data by city name city, state(optional), country (optional), start_date, end_date &city=Raleigh,NC&start_date=2018-12-11&end_date=2018-12-12
Get data by postal code postal_code, country (optional), start_date, end_date &postal_code=27601&country=US&start_date=2018-12-11&end_date=2018-12-12
Get data by city id city_id, start_date, end_date &city_id=8953360&start_date=2018-12-11&end_date=2018-12-12
Get data by ICAO or station id station, start_date, end_date &station=KRDU&start_date=2018-12-11&end_date=2018-12-12

Example Request:

https://api.weatherbit.io/v2.0/history/energy?lat=38.0&lon=-78.0&start_date=2018-12-11&end_date=2018-12-12&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":[  
              {  
                 "dewpt":33.4,
                 "snow":0,
                 "max_wind_spd":8.1,
                 "date":"2018-12-11",
                 "hdd":13,
                 "cdd":0,
                 "rh":53,
                 "wind_spd":4.7,
                 "dhi":194.8,
                 "wind_dir":166,
                 "precip":0,
                 "temp":50,
                 "t_dni":1245,
                 "t_dhi":400,
                 "t_ghi":3000,
                 "sun_hours":4.7,
                 "clouds":6
              },
              {  
                 "dewpt":45.1,
                 "snow":0,
                 "max_wind_spd":9.2,
                 "date":"2018-12-12",
                 "hdd":17.3,
                 "cdd":0,
                 "rh":98,
                 "wind_spd":5.1,
                 "dhi":61.7,
                 "wind_dir":52,
                 "precip":0.6,
                 "temp":45.7,
                 "t_dni":1245,
                 "t_dhi":400,
                 "t_ghi":3000,
                 "sun_hours":1.5,
                 "clouds":100
                 
              }
           ],
           "end_date":"2018-12-12",
           "station_id":"723114-03715",
           "count":2,
           "start_date":"2018-12-11",
           "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).
    • 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).
    • 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.
  • ]

Batch Historical Energy Weather API

This API allows you to retrieve aggregate data over a custom time period, given a start date, end date, and location. Additionally, you can specify a lat/lon bounding box, and return data for multiple stations within the bounding box (max 150 per call).

Be sure to check out our blog to read about the methodology for calculating degree days.

This API may only be used by Advanced/Advanced+ plan subscribers (See pricing).

All parameters should be supplied to the Weather API as query string parameters.

Base URL

HTTP: http://api.weatherbit.io/v2.0/history/energy/total
HTTPS: https://api.weatherbit.io/v2.0/history/energy/total
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)
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=2017-01-01&end_date=2017-01-02
Get data by city name city, state(optional), country (optional), start_date, end_date &city=Raleigh,NC&start_date=2017-01-01&end_date=2017-01-02
Get data by postal code postal_code, country (optional), start_date, end_date &postal_code=27601&country=US&start_date=2017-01-01&end_date=2017-01-02
Get data by city id city_id, start_date, end_date &city_id=8953360&start_date=2017-01-01&end_date=2017-01-02
Get data by ICAO or station id station, start_date, end_date &station=KRDU&start_date=2017-01-01&end_date=2017-01-02
Get data by bounding box lat1, lon1, lat2, lon2, start_date, end_date &lat1=38.123&lon1=-78.543&lat2=40.123&lon2=-80.543&start_date=2017-01-01&end_date=2017-02-01
* = Premium subscriptions only.

Example Request:

https://api.weatherbit.io/v2.0/history/energy/total?lat=38.0&lon=-78.0&start_date=2018-01-01&end_date=2018-02-01&threshold=63&units=I&key={API_KEY}

Example Response (JSON):


        {  
           "data":[  
              {  
                 "rh":73,
                 "wind_spd":5.8,
                 "city_id":"4770766",
                 "max_wind_spd":11.4,
                 "country_code":"US",
                 "cdd":4.7,
                 "dewpt":34.3,
                 "snow":4.6,
                 "station_id":"723114-03715",
                 "timezone":"America\/New_York",
                 "wind_dir":185,
                 "state_code":"VA",
                 "lon":"-78",
                 "dhi":150.2,
                 "city_name":"Louisa",
                 "lat":"38",
                 "hdd":603.4,
                 "t_dni":1245,
                 "t_dhi":400,
                 "t_ghi":3000,
                 "precip":5.3,
                 "temp":43.7,
                 "sun_hours":3.6,
                 "clouds":35
              }
           ],
           "end_date":"2018-02-01",
           "threshold_units":"F",
           "count":1,
           "start_date":"2018-01-01",
           "threshold_value":"63"
        }

        

Field Decriptions:

  • count: Count of returned stations.
  • start_date: Aggregation start date (YYYY-MM-DD).
  • end_date: Aggregation end date (YYYY-MM-DD).
  • threshold_units: Degree Day threshold units (F/C/K).
  • threshold_value: Degree Day threshold value in degrees.
  • data: [
    • lat: Latitude (Degrees).
    • lon: Longitude (Degrees).
    • timezone: Local IANA Timezone.
    • station: Source station ID.
    • city_name: City name.
    • country_code: Country abbreviation.
    • state_code: State abbreviation/code.
    • 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).
    • 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).
    • dni: Average daily direct normal irradiance (W/M^2) [Clear Sky]
    • ghi: Average daily global horizontal irradiance (W/M^2) [Clear Sky]
    • dhi: Average daily diffuse horizontal irradiance (W/M^2) [Clear Sky]
    • sun_hours: Average daily peak sun hours (where hourly GHI > 1000 W/m^2) over period.
  • ]