This article will give instruction on using the PurpleAir Data Download Tool. If you do not have the PurpleAir Data Download Tool installed and set up, you can learn to do so here: Setting Up the PurpleAir Data Download Tool.
If you have questions about any items in the tool, hover over the question mark ‘?’ icon next to each title to learn more.
Download Data
To download data with the PurpleAir Data Download Tool, click on the “Download” button found on the left side of the application. This will open the “Download” page. Here, you can specify the details of your request. The following sections will describe each item on the page.
Sensor Indexes
Every PurpleAir sensor has its own unique sensor index. The sensor indexes of the sensors you want to collect data from can be put into this field. If you are collecting data from multiple sensors, separate the sensor indexes with commas and do not use spaces.
Learn how to find sensor indexes here: Sensor Index.
Sensor Read Keys
On top of sensor indexes, every PurpleAir sensor has its own unique sensor read key. This key is a special code that allows you to view its data if it is private. If the sensors you are collecting data from are public, nothing needs to be entered into this field.
Place each sensor read key in this field with commas separating them. Ensure they match up in the same order as the sensor indexes in the “Sensor Indexes” field.
Learn how to find sensor read keys here: Sensor Index.
Start Timestamp in UTC (inclusive)
This field is the date to start collecting data from. Data from this date will be included in the downloaded file.
The date should be formatted mm/dd/yyyy (month/day/year) and should be in UTC.
End Timestamp in UTC (exclusive)
This field is the date to stop collecting data on. Data from this date will not be included in the downloaded file.
If the start timestamp was January 1 and the end timestamp was February 1, data will be downloaded from January 1 at the start of the day to January 31 at midnight.
The date should be formatted mm/dd/yyyy (month/day/year) and should be in UTC.
Average
This field indicates the average of the downloaded data. The following list are all valid average options:
- 0 or 2 (Real-time)
- 10 (10-minute)
- 30 (30-minute)
- 60 (1-hour)
- 360 (6-hour)
- 1440 (1-day)
- 10080 (1-week)
- 43200 (1-month)
- 525600 (1-year)
Fields
Enter the historical API fields you want to download in this field. A list of available fields is available here: API History Fields Descriptions.
Fields should be comma separated and should not contain spaces.
Save Directory
Click this button to select where the downloaded files will be saved on your computer. A new folder will be created in this directory that will contain the downloaded files.
To see the current selected directory, hover over the question mark ‘?’ icon next to “Save Directory.”
Cost Estimate
Once the appropriate input fields have been filled in, a cost estimate will be displayed here. This estimate will show how many points will be spent and the number of API requests that will be made.
To view an estimate with more detail, enable the “Show Detailed Points Cost” option in the “Settings” page.
This cost is an estimate. Some sensors may not have data for the selected time period or may not report the selected fields.
Get Data
This button will begin the requests to download PurpleAir data. If there are any errors that the tool recognizes, a message will appear to direct you to what needs to be updated.
After the requests have started, the tool will automatically transition to the “Progress” page. This page displays the current progress of the download and any errors that occur.
Once the download has finished, the data will be available in the folder that was created in the selected directory. The files will be in CSV format.
Requests will not work until your API keys are entered into the “API Keys” page of the PurpleAir Data Download Tool. You can learn how to input your API keys here: Setting Up the PurpleAir Data Download Tool.
Settings
Multiple settings are available in the “Settings” page. Descriptions of these settings are listed below.
Save API Keys
Enable this setting to save the API keys entered in the “API Keys” page. If this option is not checked, your API keys will need to be re-entered each time the PurpleAir Data Download Tool is closed and reopened.
Delay Between API Calls in Milliseconds
The PurpleAir Data Download Tool has a built in delay between making API calls. This is to help avoid being rate limited. If you are receiving errors about being rate limited, you can try increasing this setting to a higher value. The default value is 250. The minimum value is 0 and the maximum value is 5000.
Show Detailed Points Cost
If this option is enabled, the points cost estimate on the “Download” page will show much more detail, such as the cost for the fields, the cost for each request, the total cost per sensor, etc.