API Use Guidelines

We ask that you limit your API requests to as few as possible to increase efficiency, decrease costs, and keep performance optimal. This article will establish guidelines you can follow to assist with this effort.

If you are querying data too frequently or not following these guidelines, you may lose access to the PurpleAir API.

Query Multiple Sensors at a Time

The historical endpoints, at the moment, can only query one sensor at a time. The real-time endpoints can query any number of sensors at once. If you have multiple sensors from which you want to collect data, it is better to use as few requests as possible.

​There are various methods of querying multiple sensors.

  • ​You can use the GetSensorsData request to query all sensors that have data matching user-specified fields. In that same request, you can create a bounding box using latitude and longitude values to query all sensors within that zone.

  • The PurpleAir API also has grouping functionality. You can add several sensors to a single group and query the entire group simultaneously with one request. More information is available in our API guide.

There are plans to release endpoints that allow you to query the history of multiple sensors at once. Until that has been implemented, the above-mentioned strategies will help you avoid getting rate-limited or losing access to the API.

Query Real-Time Data Rather than Recent History

If you are building a sensor database with new data, it is better to use the real-time API rather than the historical API. Real-time data is instantly available in memory. As mentioned above, the real-time API can also query multiple sensors at once. All-in-all, it is much more cost-effective and less server-intensive for PurpleAir.

A group of sensors can be queried every minute with the real-time API with a single request. That data can then be stored in your database.

If a real-time request fails, the historical API can be used to fill in the missing data.

Spread Out Requests at Regular Intervals

PurpleAir sensors report data every two minutes. This means that it may not be necessary to query data faster than every minute with the real-time API.

For the historical API, we ask that you stay below or around 1000 requests per day.

Large Amounts of Data

If you are looking to collect historical data for a large number of sensors, we ask that you do not use the historical API. Querying many sensors with the historical API will likely cause you to pass rate limits and your API keys to be paused.

Instead, contact us at contact@purpleair.com with your request for data, and we may be able to provide the data in a more efficient way.

Access the Historical API

Access to the historical endpoints is restricted. Learn how to gain access here: Historical API Endpoints are now Restricted.