Our weather data provided through APIs is not priced by usage, but rather each plan is restricted to the amount of API calls an application can make in a given time period (rate-limiting by hour, day and month).
What's an "API call"?
API (Application Programming Interface) is just a tech term for a tool that gets data from a database so a developer can display that data in their application, such as ClimaCell's collection of data layers like weather, air quality, pollen etc. Our API endpoints give developers a common, systematic way to pull that data into whatever program they want to use via a single API. Doing so is called an "API call", whereas the developer calls the database, asks for a specific piece of data, and the database sends back that data.
How is an API call counted?
ClimaCell's plans differ in restrictions of API calls, therefore it's important to understand exactly how much data you can get with an API call.
1 endpoint, 1 location = 1 API call
For the data endpoints, one API call gets all time steps of a data type (realtime/forecast/historical) for a specific time period for one location. For example, /realtime returns the requested data fields for a lat/lon right now. And so, a developer building an application would be charged one API call to get this location's numerical data.
Similarly, requesting a single map tile is equivalent of a single location only with that the data format is visual (png image) and the location data spread (or area) is defined by the zoom level. If a developer requests a x,y,z tile the precipitation that is occurring now, they will consume 1 call out of their limit. Therefore, requesting a tile for one location is also a single call.
Lastly, ClimaCell widgets are also counted in the same manner, such that each forecast update is a single API request.
Wait, what is "rate-limiting"?
"Rate-limiting" is used to control the amount of incoming and outgoing calls to the API. It is used to protect the API from inadvertent or malicious overuse by limiting how often each of our users can call the API. Without rate limiting, a user may request as often as they like, which can lead to “spikes” of requests may "starve" other users from using the API.
Let's say you're on the Free plan that is configured to allow 1,000 requests/day. If the number of API calls you make exceeds that limit, then an error will be triggered and you will not be able to get the data until the day. ClimaCell API has rate set on an hourly, daily and monthly basis (or fixed windows) for each of our plans.
How can I monitor my usage?
You can track the daily and monthly usage of your account by signing in and going to the development section. If you'd like to check programmatically, there are also response headers for each call specifying your plan's rate limit and the remaining calls as explained in the reference docs.
You're not alone. Feel free to reach out to email@example.com to chat with our team regarding any specific examples or use cases you are tackling. If you think you a higher rate-limit than your current plan configuration, please contact firstname.lastname@example.org to learn more about our tailored offering for Enterprise customers.