Degree Days

Degree Days

Weather Data for Energy Saving

API Rate Limits in Detail

Our pricing and sign-up page has a good overview of how the API rate limits work, and a useful calculator for estimating what rate limit you'll need. This page is for if you want more details:

Requests and responses - how the API works

When choosing your account plan, it helps to understand roughly how the API works. You don't need to be technically minded.

Rate limits and request units explained

Calculating degree days is an intensive process. A typical request for data requires our system to access and churn through many thousands (often millions) of temperature readings. The resulting degree-day figures are simple, but the process that generates them is anything but.

Rate limits enable us to manage the processing load and keep our service running efficiently and sustainably. They make it possible for us to offer account plans to suit a wide range of use cases and budgets. And they are easy for other software systems to work with: if a system reaches its rate limit in any given hour, it only has to wait until the next hour to make requests again.

When you choose your hourly rate limit, you are effectively reserving a slice of our system's data-generation capacity for use when you need it.

Each API request that you make will bring you closer to your hourly rate limit. If you reach your rate limit in any given hour, you will need to wait until the next hour before making more requests.

The rate limit works with "request units". Some requests count as just one request unit, but requests that require more processing (e.g. those that fetch more than a year's worth of data) count as more than one request unit.

Working out how many request units a request will count as:

  1. All API requests count as 1 request unit at a minimum.
  2. For a request for a single set of data, it's 1 request unit for each year of data coverage. For example, a request for a year's worth of data counts as 1 request unit, 2 years counts as 2 request units, 3 years as 3, 4 years as 4, and so on.
  3. You can fetch up to 100 data sets for a location in a single request (e.g. HDD and CDD in 50 different base temperatures each). For 100 data sets multiply the number from step b by 5; for between 1 and 100 data sets the multiplier follows a simple sliding scale between 1 and 5.
  4. Add on 1 extra request unit if you are fetching data for a "geographic location" (i.e. if you are specifying the location you want data for as a longitude/latitude or postal/zip code instead of using a specific weather-station ID).

Note that additional request units are only added if the request goes through successfully. If, for example, you request 10 years of data from a weather station (10 request units in total), but only 5 years of data are available, then your request will only count as 5 request units. If you specify a geographic location for which no good data can be found, then no additional request units will be added for that request.

The above is for a LocationDataRequest (the type of request you use to fetch degree-day data). A LocationInfoRequest (which enables you to find out which weather station the API would use to generate the data you specify from the geographic location you specify, without it actually generating the data) will always take 1 request unit. This can be useful if you are storing data by station ID in a database... For any geographic location (e.g. building location), you can make a LocationInfoRequest to find out which weather station the API would use to generate the data you want, but then save request units by only making a LocationDataRequest if the data is not already in your database.

Rate limits on location-limited account plans

The location-limited account plans are primarily limited in terms of the number of locations that they can be used to fetch data from. Allowed locations are set automatically as requests for data are made (allowing for a limited number of changes over time).

The location-limited plans are also rate limited in terms of the number of requests that can be made per hour. These limits are unlikely to be reached by well-programmed software using the API for typical use cases.

© 2020 BizEE Software - About | Contact | Privacy | Web Tool | API | Integration Guide | API FAQ | API Sign-Up