PurpleAir Data Download Tool

Data API
1

This article is related to the PurpleAir API. If you are unfamiliar with it, check out our About the PurpleAir API page to get started.

The PurpleAir Data Download Tool is an open-source tool for downloading PurpleAir data from the PurpleAir API. This tool does not require any programming experience to use, and will allow you to view air quality data from any time period.

Our API use guidelines should be adhered to while using this tool.

Installation

We an have article on setting up this tool here: Setting Up the PurpleAir Data Download Tool.

To download and install this tool, click on one of the direct download links below or visit the repository and open the “src-tauri” folder and then the “target” folder. Once there, open the folder matching your operating system. The application file will be inside of that folder for you to download.

A video tutorial on the installation can be found here. Note that the download location in this video is incorrect. Use the links above to find the correct download file. Everything else is correct. The timestamp for the Mac installation is 1:26 and the timestamp for the Windows installation is 0:00.

For MacOS the Data Download Tool will need to be enabled in your privacy and security settings. This process can be seen in the video installation guide above.

A video tutorial on the usage of this tool is available in the same video at 2:53.

An article explaining how to download data is available here: Using the PurpleAir Data Download Tool.

Requirements

You will need PurpleAir API keys with history access to use the tool. API keys are issued per user, not per sensor. If you do not have keys, you can create them here: PurpleAir Develop.

Learn more about creating and managing API keys here: Creating API Keys.

Our API use guidelines apply to the use of this tool. Review our API Guidelines here: API Use Guidelines.

If you make a large request, the tool may freeze when your computer goes to sleep. We recommend keeping your computer from sleeping while making a large request or splitting it into multiple requests.

Issues and Feedback

The project link on GitLab contains more information about the tool and its use. If you run into issues while using the tool, please use the issues tab in GitLab to inform us of them. You can also send an email to incoming+purpleair-api-clients-data-download-tool-42571353-3rvhlnmngnj1xhzwzy885pxn4-issue@incoming.gitlab.com.

The tool is open source, and we encourage contributions and feedback. We will continue to improve this tool in the future.

Learn More

How to Make Efficient API Calls
What’s the Difference Between CF=1, ATM, and ALT?
What’s the Difference Between Raw PM2.5 and an AQI Scale?

7 Likes
2

I can not make this tool work and the info on Github is of no help.
The issue seems to be in the “fields”. I have listed several fields
exactly as given in the PA documentation, but error is “invalid fields”.
Even when I used a simple field like “temperature” i get this error message:
Error Code: 403
Error: ApiDisabledError
Description: API calls to this endpoint (get_sensor_history) have been restricted. Please try again later or contact PurpleAir for more information.
Making request 1.

1 Like
3

Hi @Dan_Jaffe,

This tool requires access to the historical API. As the error message mentions, access has been restricted. However, I have just enabled access to the history endpoints on your API keys. Try again, and see if you are now able to download data.

Let us know how it goes. If you continue to receive this error message, email us with your API keys so we can ensure that history access is granted.

1 Like
4

Does it cost to access our own historical data? I’m getting this error message.

Starting requests for sensor XXXXXX.
Making request 1.
Error Code: 402
Error: PaymentRequiredError
Description: Payment is required to make this api call.
This error means that your project does not have enough credits to make this API call. You can visit develop.purpleair.com to add points to your project or top up your account.
Due to this error, the process is being aborted…

Process has been aborted!

5

Hi @KG949, this article may help answer some of your questions: New API Online Dashboard.

New API keys starts with one million points. You can add these points to your project by following the steps in the article noted above. This will allow you to query data with the API.

1 Like
7

HI Purple Air,

When I download data directly from the Sensor Map, I have the option to automatically apply the EPA’s conversion to the data. I am attempting to collect 3 years of historical data from a few sensors through the download tool. I see no options for applying the EPA’s conversion when using this tool, is it automatically applied or do I need to convert the data manually?

1 Like
8

Hi @Raisch_Tomlanovich, you will need to apply the conversion factor manually. However, we have plans to implement a feature to get conversion factors already applied to the data. We hope to include this in a future update.

If you have any feedback or ideas, we’re happy to hear them.

1 Like
9

I’m confused. Your terms of service (4.5) forbid use of open source software:

No Open Source Materials. In creating any Licensee Data Derivatives as allowed per the terms herein, Licensee shall not incorporate, derive from, or otherwise use any Open Source Materials (as defined below).

“Open Source Materials” means any software or data that is licensed under terms that require as a condition of use, modification and/or distribution of a work: (i) the making available of source code or other materials preferred for modification, (ii) the granting of permission for creating derivative works, (iii) the reproduction of certain notices or license terms in derivative works or accompanying documentation, (iv) the non-assertion of patents or other intellectual property rights or granting of a royalty-free license to any party under intellectual property rights regarding the work and/or any work that contains, is combined with, requires or otherwise is based on the work; or (v) the source code or data is made publicly available under a license that does not require any manifestation of assent by the licensee but rather permits the licensee to use the software or data in accordance with and subject to the applicable terms and conditions, including without limitation, under the GNU General Public License (GPL) or Lesser/Library GPL (LGPL), the BSD license, the MIT license, the Artistic License, the Mozilla Public License, the Common Public License, or the Sun Community Source License (SCSL).

The downloader tool is provided with the MIT license, so using this downloader tool is a ToS violation.

2 Likes
10

Hi @altarona,

This section refers to the usage of PurpleAir data. PurpleAir data cannot be distributed using open-source software. Users who want to access PurpleAir data must obtain it directly from PurpleAir’s official sources.

For example, I cannot put a sample of previously downloaded data in the PurpleAir Data Download Tool. If that data is accessible to the end user, I provided that data to them instead of it coming directly from one of PurpleAir’s official sources.
​
​Since the PurpleAir Data Download Tool uses the user’s API keys and downloads data directly from PurpleAir, the terms of service are not being violated.

The PurpleAir Data Download Tool is still open-source and can be distributed. The data collected through the PurpleAir Data Download Tool cannot.

3 Likes
11

Hi Ethan and community,
I can tell that all my questions are “sort of” answered here. But not quite. I want to:

  1. potentially access “all” historic outdoor sensor data. Idea is to do spatial/temporal comparisons with NASA, NOAA (and other - around the world) satellite data including geostationary data at 10 minute or better intervals.
  2. Be able to filter based on “A” and “B” differences
  3. Be able to apply a variety of corrections depending on aerosol type (dust, woodsmoke, etc.)
    I used to do this via the PA website, but obviously not anymore with the API.
    So,
    a) can anyone help me set up a script to do this?
    b) What does a million points mean (what does it buy)?

Thanks!

1 Like
12

Hi @rclevy, I will respond to your questions in the order they were asked:

  1. If you want to collect all historical outdoor sensor data, we recommend contacting us at contact@purpleair.com with further details of your inquiry. We can collect the data more efficiently when it comes to several thousands of devices. Please note that there will be costs associated with this request.

  2. A and B channel data are available through the API, and this can be provided.

  3. Correction factors cannot currently be applied to the data through the API. However, a script could be written once the data is collected.
    a. We are happy to help you find the correct formulas for the required conversion factors.
    b. We have a couple of examples of what the one-million starting points can purchase here: API Pricing.

1 Like
13

Thanks Ethan,

To motivate the kind of activity I am trying to do… Here are two animations. (when I could do for free last year).

(Attachment PurpleAir_CONUS_06Jul2022A_night.mp4 is missing)

(Attachment ABI_RGB_PurpleAir_20200308.mp4 is missing)

1 Like
14

Any chance of making a Linux version? Debian/ubuntu?

3 Likes
15

Hi @Eric,

Our apologies, but we are not able to create a Linux version at this time.

However, if you have programming experience, you can clone the repository and attempt to build it yourself. If you want to try this, the following page may prove helpful: Linux Bundle | Tauri Apps.

We will also be updating the readme to include more information about building the tool on your own devices.

1 Like
16

If you are till find answer to this, I will be glad to help.

I have a writeup I put together for the whole process on how to download PurpleAir historical data in a particular area and coordinates of sensors in that areas.

1 Like
17

Hi @opejinabdul, do you have some script to do this?

1 Like
18

hi, I’m trying to update the version of the PA Data Download Tool to 1.2.2 but the links in gitlab and at this Community Forum post to the application file (e.g. “PurpleAir Data Download Tool_1.2.2_x64_en-US.msi”) seem to be broken. I tried different browsers. Could PA please advise?

1 Like
19

@purplebrian the links are still active when we try to download them. Are you able to try accessing the link in a new tab?

1 Like