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.
Attribution
Follow the PurpleAir Attribution Guide for proper logo use and data sourcing. This guide refers to any use of PurpleAir visual data or use of the PurpleAir API (https://api.purpleair.com/).
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. We do not have a timeline at this time.
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.
Use the “modified_since” Field
The “modified_since” field in the API will filter out any sensors whose data has not been modified since the provided timestamp. This will allow you to consume less points by only collecting new data and avoiding repeat data.
Using the “time_stamp” from the previous real-time API request as the “modified_since” field in the next request will avoid repeat data.
Query Only Needed Fields
Every API field has a point value associated with it. The points table is available on develop.purpleair.com under the “Pricing” tab. To reduce the number of points used per API call, decrease the number of fields you are querying to only those you will use.
Avoid Querying Metadata Frequently
Metadata includes fields such as “hardware,” “firmware_version,” “latitude,” “longitude,” “altitude,” “name,” etc. These fields do not change often and will likely return the same data when queried again. Limit frequent requests for these fields to avoid spending points on repeat 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 (several thousands of sensors), we ask that you do not use the historical API. 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