API Rate Limits in Detail

Our pricing and sign-up page has a good overview of how the API rate limits work, and an API plan selector to help you estimate 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 API plan, it helps to understand roughly how the API works. You don't need to be technically minded.

Your software sends a request to the API, specifying what data you want, and for what location. For example, you might request 12 months of 65F-base-temperature heating degree days from KNYC (a weather station in Central Park, New York).
The API will send back a response containing the data you requested or a failure code if the data could not be generated. KNYC has good temperature data so a failure for that station would be unlikely, but not all stations have good data.
You can fetch more data by sending more requests. If you want data for 800 different locations, just make 800 requests – one for each location.
You can fetch up to 120 sets of data with a single request, provided they are all from the same location. For example, you might want to fetch HDD and CDD in 60 different base temperatures each. Or HDD, CDD, and hourly temperature data, all in one request.
You can specify the location you want data from as a weather station ID or as a geographic location (either a longitude/latitude point or a postal/zip code). If you specify a geographic location, the API will choose a nearby weather station automatically and generate your data using that.

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 API 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:

A LocationDataRequest enables you to fetch degree days and/or hourly temperature data (you can fetch multiple sets of data for a location in one request). Its request units are calculated as follows:

First, consider all the sets of degree days together. Work out the period of time between the earliest date and the latest date covered. Add 0.96 request units for each year (or partial year) of coverage. That's 0.96 for up to 1 year, 1.92 for up to 2 years, 2.88 for up to 3 years, etc.
Next, consider each individual set of degree days, and work out the period of time that it covers. Add 0.04 request units for each year (or partial year) of coverage. That's 0.04 for up to 1 year, 0.08 for up to 2 years, 0.12 for up to 3 years, etc. Do this for each set of degree-day data in your request.
Consider each set of hourly temperature data. Add 2 request units, or 1 if it is not the first set of hourly temperature data in your request or if you are also fetching degree days (for which we will already have done some of the processing necessary to calculate hourly temperatures). Then add 0.2 request units for each month (or partial month) of coverage. Do this for each set of hourly temperature data in your request.
Add 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).
Round the total to the nearest whole number.

For example, consider a LocationDataRequest specifying HDD and CDD covering the last 5 years, in 10 different base temperatures each (i.e. 20 sets of degree days in total), and hourly temperature data covering the last 18 months, all for the longitude/latitude position of the Eiffel Tower (longitude: 2.2945, latitude: 48.8584, in case you are interested):

Together all the sets of degree days cover 5 years, so that's 5 × 0.96 = 4.8 request units.
For each set of degree days covering 5 years, add 5 × 0.04 = 0.2 request units. For 20 sets of degree days that's 20 × 0.2 = 4 request units. Adding this on to the total from step 1 gives us 4.8 + 4 = 8.8 request units.
For one set of hourly temperature data covering the last 18 months, it's 1 + (18 × 0.2) = 4.6 request units (it starts with 1 rather than 2 because the request is also fetching degree days so we are already doing some of the processing necessary to calculate hourly temperatures). So in total we now have 8.8 + 4.6 = 13.4 request units.
The longitude/latitude position is a geographic location (as opposed to being a weather station ID) so we add 1 extra request unit, giving us a total of 13.4 + 1 = 14.4 request units.
Rounding 14.4 to the nearest whole number gives us a total of 14 request units for this one request.

If we wanted to fetch the same data for 1,000 different longitude/latitude locations around the world, we'd make 1,000 requests (one for each location) and we would expect it to count as 1000 × 14 = 14,000 request units in total.

If a request fails, or fails to return as much data as requested, it will always count as 1 request unit at a minimum, but additional request units are only added for the parts of the request that went through successfully. If, for example, you request 10 years of degree days from a weather station (10 request units in total), but only 5 years of degree days are available, then request units will be calculated for 5 years of degree days rather than 10. If you specify a remote geographic location for which no usable data can be found, that request will count as 1 request unit only.

A LocationInfoRequest 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. It 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 API plans

The location-limited API plans are 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 API plans are also rate limited in terms of the number of request units per hour. We don't publish these limits, but they are high enough for well-programmed software to fetch regular data updates (typically daily, weekly, or monthly) for a fixed set of locations that is within the number allowed by the plan. They won't stretch much further than that though, so we don't advise using them for development (the test account is a better choice).

Choose your API Plan and Start Today!