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.
Large Amounts of Data
If you are looking to collect a large amount of historical data, we ask that you do not use the historical API. If you are requesting data for a large number of sensors or are querying a large date range paired with a short averaging period, this will likely cause you to pass rate limits and your API keys may be disabled.
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.
If you are unsure if your request counts as a large data request, reach out to us first with the details of your request and we can provide guidance.
API Keys
Create and manage API keys here: PurpleAir Develop
Learn more about managing API keys here: Creating API Keys
Attribution
Please be aware of our attribution guidelines, which can be found here.