The PurpleAir API
The PurpleAir API is a web service that allows you to obtain air quality data reported by PurpleAir sensors. This is an extensive dataset going back to early 2016.
Users wanting to jump straight into the technical details can create an account and utilize our API documentation to make queries.
Aside from using the API, you can get data from PurpleAir sensors in various other ways. You can click here for a complete list. Some of the more common ways are:
- Downloading data viewed on the PurpleAir Map
- Querying a Sensor Locally Over WiFi
- Recording data to a microSD card for SD-capable sensors
Getting Started
Points-Based System
Before we begin, it’s important to note that the API is a points-based system. For API calls to be successful, you must have the required number of points in your Organization.
All new API users receive 1 million points upon signing up, with further points available for purchase. Our article on Making Efficient API Calls provides tips that can help reduce your point usage.
Sensor owners don’t need to pay for data from their sensors; view our API Points for Sensor Owners article for more information.
Creating an Account / Organization
To use the API, you’ll first need to create an account on the Developer Dashboard. To do this, simply log in to https://develop.purpleair.com with a Google account. You can also Google Associate a non-Google email address to log in.
Accounts are also known as “Organizations” because you can add other users to them. If you would like to add another user to your organization, send an email to contact@purpleair.com.
Creating Keys
Once your account is created, you’ll need to create API keys. API keys function similarly to a password. They are directly connected to your account and must be used to request data from the API.
Example Key: B144C732-11DE-11EE-A445-42098A784009
It’s important not to share these keys, as anyone with them can use your account to obtain data.
Using the API
Once you’ve created an account and API keys, you can start using the API.
Those familiar with programming can examine our API documentation and query the API directly. Our article on Making API Calls with the PurpleAir API also provides an introduction for users who would like to learn how to do so.
For those without any programming experience, using the Data Download Tool is the easiest way to obtain historical data. Click here for instructions on how to set up the Download Tool and start using it.
Sensor Indexes
To obtain data from a specific sensor, you’ll need to find its sensor index. Using a sensor’s index is always required when using the Data Download Tool.
If your sensor is privately registered, you’ll also need to obtain your sensor’s private read key.
Data Available From the API
Data is returned in JSON format by default
Real-Time Data
The latest data reported on the PurpleAir network can be queried using real-time API endpoints. The Get Sensor Data endpoint allows you to query a single sensor, while the Get Sensors Data endpoint allows you to query multiple sensors in the same call There is no limit to the number of sensors you can query in a Get Sensors Data call.
Historical Data
If you would like historical data, you can use the Get Sensor History endpoint. This endpoint allows you to query a time range of data for a single sensor. A CSV endpoint is also available for historical data.
The amount of data you can retrieve at once is limited based on the averaging period requested. Further information is available in our Looping API Calls for Historical Data article.
Groups
If there’s a set of sensors you expect to query frequently, you can create a group to simplify your API calls. Endpoints available for groups mirror those for the real-time and historical APIs. Real-time data can be queried for the entire group at once, while historical data must be requested for a single sensor at a time.
The Data Download Tool can currently only download historical data
Support
Using APIs can be complicated. If you have any questions or would like support, please make a community post or send an email to contact@purpleair.com. We are happy to help.
Learn More
API Pricing
Using the API Dashboard
Making API Calls in Other Programming Languages