How to Get Historical Sensor Data Step-by-Step Using the Data Download Tool

Data API
1

The following guide is meant to provide clear steps for retrieving historical data from a sensor using our Data Download Tool. For a more complex and comprehensive introduction to our API, you can read our About the PurpleAir API article.

 

Follow the steps below to attain historical data from a sensor from start to finish. The steps are split into three parts: creating an API account, setting up the Download Tool, and Downloading Data.

Creating an API Account

Before you can download PurpleAir sensor data, you need two things:

  1. A PurpleAir Develop Account
  2. An API Read Key

If you already have an API read key, skip ahead to Setting Up the Download Tool.

Step 1 – Create an Account

  1. Go to develop.purpleair.com.
  2. Sign in with a Google account under “Sign in to your account.” When you log in for the first time, a develop account is automatically created.

This requires that you use a Gmail or other email connected to a Google account. This email does not have to be connected to your sensors.

Step 2 – Create an API Read Key

  1. In the top navigation bar, click API Keys.

Navigation-bar

  1. On the right side, click the button + API Key.

+APIKey

  1. Fill out the form. Select your project (one should be auto-generated for you), leave everything else the same, and click Create.

Project
Project447×137 4.38 KB

  1. Your new API Read Key will now appear in the API Keys tab.

Keep this tab open, as you will need to copy that key into the Download Tool later.

Step 3 – Reach Out About Points

Each API request costs points. But, if you’re pulling data from your own sensors, we do not want you to pay for that data. As such, we will grant you enough points to retrieve the data you’re looking for. More information is available here: API Points for Sensor Owners.

  • To get API points, send an email to contact@purpleair.com. Include your developer account email and mention that you’re querying your own sensors.

Setting Up the Download Tool

Now that you have a read key, you’ll want to connect it to the PurpleAir Data Download Tool. If you don’t have an API read key, go to Creating an API Account above.

Step 1 – Download and Install the Tool

  1. Download the Data Download Tool: PurpleAir Data Download Tool

  2. Open the installer and follow the setup steps. If you’re on Mac, you’ll need to authorize the program in your Privacy & Security settings.

    • Go to System Settings > Privacy & Security.
    • Authorize the file, then reopen the tool.
    • A video guide of this process can be found here.

Step 2 – Add Your API Key

  1. In the Download Tool, click API Keys (left menu).

  2. Copy your API Read Key from the Developer Portal and paste it into the API Read Key field.

  3. On the left menu, click Settings.

  4. Check the box Save API Keys.

    • This ensures your key is remembered and you don’t have to paste it in every time.

Setting Up An API Request & Downloading Data

This section covers what you need to do to set up and execute an API request in the Download Tool.

Step 1 – Open the Download Tab

  1. In the left menu, click Download.

  2. This tab is where you’ll define your API request:

    • Which Sensor(s) you’re getting data from.
    • What type(s) of data you want.
    • What date range and average of data you want.

Step 2 – Find and Enter Sensor Indexes

  1. Every PurpleAir sensor is identified by a unique number called the sensor index. You’ll need this index to request data from that sensor using the API or Data Download Tool. Here are two ways to find it:

    • Check your registration email: If your sensor was registered after October 15, 2024, the confirmation email includes the sensor index.
    • Find it on the map: If you don’t have the email or registered before that date, go to the PurpleAir Map, locate your sensor, and click on it. In your browser’s URL bar, look for a section that says select= followed by a number. That number is your sensor’s index.
    • If you can’t find your sensor’s index using the steps above, go here: Sensor Indexes and Read Keys

  2. Once you have the index, paste it into the Sensor Indexes box. If you’re entering more than one index, separate each with a comma, no spaces. For example: 12345,67890,11223

Step 3 – Handle Private Sensors (If Needed)

Skip this step if your sensors are public. This only applies to private sensors.

The next fields, Sensor Read Keys and Privacy, are only important if you are getting data from sensors that are privately registered.

  1. Enter your private sensor’s read key into the Sensor Read Keys Field. If you don’t have the key(s), follow the same instructions as above for attaining sensor indexes. If you are querying multiple sensors, you’ll need to list the read keys in the same order as the corresponding indexes. Again, separated by commas, no spaces.
  2. Set the Privacy field to both. This ensures you’ll get both the public and private data from a device.

Step 4 – Define Your Date Range

Timezone, Start Timestamp, and End Timestamp all pertain to the period of time for which you want to get data.

  1. Timezone: UTC is the default, but this can be changed to your local timezone.
  2. Start Timestamp is inclusive, meaning that if you set it to 01/01/2025, you will receive data starting on 01/01/2025.
  3. End Timestamp is exclusive, meaning that if you set it to 01/01/2025, you will receive data ending on 12/31/2024.

For example, if you want a week’s worth of data from January 1st to January 7th, set Start to January 1st, and End to January 8th.

Step 5 – Choose Data Frequency (Averages)

  1. The Average field controls the frequency of data you receive.
    • Real-time (2-min) → one average over a 2 minute period.
    • 10-minute → one average over a 10 minute period.
    • 30-minute, 1-hour, daily, etc. → longer averages.

For example, if you request real-time averages for an hour long period, you’ll receive 30 data entries. But, if you request 10-minute averages for the same period, you’ll only receive 6 data entries.

Step 6 – Select Data Fields

This is where you you choose the type(s) of data you want to retrieve. For example, the main pollutant that PurpleAir sensors measure is particulate matter (PM). But, you can also get things like Temperature, Pressure, and Humidity.

Step 7 – Choose a Directory and Run Your Query

  1. Under Save Directory click Select Directory. Pick a folder on your computer where you want the data file saved. You’ll find the downloaded file there once the download completes.

  2. Click Get Data and watch the download progress. Once it finishes, click Reveal Directory to open the saved data file.

  3. You’ve now successfully downloaded PurpleAir data!

Learn More

How to Obtain Sensor Data
How to Make Efficient API Calls
How to Tell When a Sensor Produced Data