Data Download and Export

Once your AirGradient monitor is successfully connected to WiFi, the device will begin transmitting real-time air quality data to the AirGradient dashboard.

In addition to viewing live data, the platform allows for historical data to be collected and stored. This historical data can be exported for further analysis, enabling you to identify air quality trends over time and gain deeper insights into the environmental conditions of your location.

Note: You may access the glossary to guide yourself as there may be terms that you may not be familiar with as you go through this chapter.

1. Prerequisites

To export data from your AirGradient monitor, ensure the following:

• AirGradient Monitor Connected to WiFi and Plugged In: Your monitor must be powered on and connected to a WiFi network. This ensures it can collect air quality data and transmit it to the AirGradient server. Only data sent to the server will be available for export.
• Device with Internet Connection: You will need a device with internet access to export data, either through the AirGradient dashboard or using the API. While smartphones and tablets are supported, we recommend using a computer for the most comfortable and efficient way to manage the data export process.
• AirGradient Dashboard Account: To export data, you need an AirGradient dashboard account linked to the monitor you wish to export from. For account creation, you will need a valid email address.
• Program to Read CSV (If Exporting via CSV): If you choose to export your data via the CSV option from the dashboard, ensure that you have a program, such as Excel or Google Sheets, that can read and process CSV files.

2. Data Retention and Export Options

AirGradient provides flexibility in how you can export your data, but it’s essential to understand the data retention periods and available export options.

• Exporting Raw vs. Bucketed Data:
  • Raw Data: This is the unprocessed data as it was collected by your monitor. Raw data can be exported directly from the dashboard or through the API. Compared to bucketed data it contains slightly more information, e.g. the raw signal of the TVOC sensor which is primarily useful for scientific analysis and in-depth research, but for most purposes, bucketed data provides all the essential insights needed.
  • Bucketed (aggregated) Data: AirGradient aggregates data into predefined time intervals (buckets) for easier analysis. Bucketed data offers a higher-level overview and is helpful when you need summarized data over specific time ranges, such as hourly or daily. Keep in mind that the size of the bucket will affect the file size — larger buckets (e.g., daily) will result in smaller files, while smaller buckets (e.g., hourly) will generate larger files.
• Raw Data Retention Period: The raw data from your monitor is available for a limited time. Once the retention period ends, older raw data cannot be exported. By default, the retention period is 10 days. If you need extended access, please contact our support team to request an extension.
• Bucketed Data Retention Periods: Data aggregated into smaller buckets (e.g., 5-minute or 30-minute buckets) is available for up to 150 days. After this period, only larger buckets (e.g., 1-hour, 1-week) will remain accessible for analysis and export.

3. Data Export Options Overview

There are two ways to export data from your AirGradient monitor:

1. Export via the Export Page on the AirGradient Dashboard: You can export data directly from the AirGradient dashboard through an intuitive export page. This method provides a simple, web-based interface, and the data will be exported in CSV format.
2. Export via the AirGradient API: If you prefer automating the export process or need to integrate data with external systems, you can use the AirGradient API. This method provides greater flexibility and allows you to export the data in JSON format, suitable for advanced use cases and data integration.

3.1 Data Export via the Export Page in the AirGradient Dashboard

To export data via the AirGradient dashboard, follow these steps:

1. Log In to Your AirGradient Account: Navigate to the AirGradient Dashboard and log in with your credentials. Make sure the monitor you wish to export data from is linked to your account.

2. Access the Export Page: In the dashboard, go to the Data Export page. You will find this inside the side navigation menu.
   

   

3. Select Location and Bucket Size: Start by choosing the location (monitor) from which you want to export data. Along with selecting the location, you’ll need to choose the bucket size. If you prefer raw data, select the “raw” option instead of a bucket size. For bucketed data, pick the desired bucket size (e.g., 5 min, 10 min).

   

4. Select Date Range: After selecting the location and bucket size (or raw data), choose the date range for which you want to export data. You can select a custom range based on your needs.
   

   

5. Export the Data: Once you’ve made your selections, click on the “Download” button to generate and download the data file. Your data will be prepared in CSV format and the download will start automatically.
   

   

6. Open the CSV File: To view the exported data, you can open it in Google Sheets or any other spreadsheet program like OpenOffice:

• In Google Sheets, go to Google Sheets, create a new sheet, and import the CSV file by selecting “File” → “Import” → “Upload.”
• Once the file is uploaded, the data will be displayed in columns with air quality parameters and timestamps. Use this cheatsheet to know what the parameters (in the column headers) mean!

3.2 Data Export via the AirGradient API

Alternatively, AirGradient offers a public API for exporting data programmatically. To export data using the API, follow these steps:

1. Obtain an API Token: In your AirGradient dashboard, go to the General Settings page under the Connectivity tab. Enable API access, and once successful, you will receive a unique API token.
   

   

2. Explore the Public API Endpoints: You can find all available public API endpoints in the Swagger Documentation. This page allows you to try out the necessary endpoints and provides descriptions for each, including the required parameters.
   

   

3. Identify the Location ID: Some of the endpoints require location ID. It refers to the unique ID of the location that your monitor is linked to. It is not the name of the location. To find it, go to your dashboard’s Locations Administration page. In the table of all locations, identify the desired location, and the location ID will be displayed in the first column.
   

   

4. Include Your API Token and Location ID: When making a request, include the API token and location ID (if applicable) that you retrieved from your dashboard in the relevant fields.

   

5. Receive and Use the Data: The API will return the data in JSON format. After receiving the data, you can integrate it into your system or use it for further analysis.

4. Data Accuracy and Correction Algorithms

AirGradient has developed correction algorithms for various air quality parameters to enhance the accuracy of the measurements displayed on the dashboard.

If you are using exported data for further analysis or reporting, keep in mind that there are two columns of PM_2.5 data: raw (uncorrected) and corrected. Raw data may differ from what is displayed in the dashboard due to these corrections. The correction formulas are publicly available on the AirGradient website (see link below).

For more details about our correction algorithms and how they enhance data accuracy, please visit our Correction Algorithms Documentation.

5. Frequently Asked Questions (FAQs)

Does AirGradient limit access to my monitor’s data?

No, AirGradient embraces an open-data approach, ensuring you have full access to all the data collected by your monitor. You can view, export, and analyze both real-time and historical data without restrictions.
Keep in mind that raw data is only available for export only until the end of the retention period. However, bucketed data remains available.

What is the difference between raw data and bucketed data?

Raw data is the unprocessed data collected directly from your monitor, while bucketed data is aggregated into time intervals (e.g., 5 minutes, 10 minutes) for easier analysis. Compared to bucketed data it contains slightly more information, e.g. the raw signal of the TVOC sensor which is primarily useful for scientific analysis and in-depth research, but for most purposes, bucketed data provides all the essential insights needed.
You can choose either format when exporting your data, but raw data is only available for export until the end of the retention period.

How long is raw data available for export?

By default, raw data is available for 10 days. After this period, the older raw data cannot be exported. If you need a longer retention period, you can contact our support team to request an extension.

What is the retention period for bucketed data?

Bucketed data with smaller time intervals (e.g., 5-minute or 30-minute buckets) is retained for up to 150 days. After this, only larger buckets (e.g., 1-hour, 1-week) will remain available for analysis and export.

How can I extend the retention period for raw data?

If you need to retain raw data for longer than the default 10 days, please contact our support team. They can assist you in extending the retention period according to your needs.

Can I export data using a smartphone or tablet?

Yes, you can export data using a smartphone or tablet. However, for a more comfortable and efficient experience, especially when managing larger data sets, we recommend using a computer. Additionally, you may need specific apps like Google Sheets or Excel to open and work with the exported CSV files on mobile devices.

Why am I getting a 404 error when trying to export data?

If you receive a 404 error while attempting to export data, it may be because no data is available for the selected time period. This can happen if the selected date range falls outside the retention period for raw data or if there was no data recorded during that time.

You can check whether the selected period contains data by visualising it on the Dashboard. To check whether the retention time is causing the issue, try to download the selected period at higher bucket sizes.

What program do I need to open CSV files?

CSV files can be opened in programs like Excel, Google Sheets, Open Office or any spreadsheet application. Some programmes can be used online, while others are desktop-based and need to be installed first.

Where can I find API documentation and endpoints?

All available API endpoints can be found in the AirGradient Swagger Documentation, where you can explore and test the endpoints.

How do I get the location ID for API requests?

To find the location ID, go to the Locations Administration page in your dashboard. The location ID is listed in the first column of the table that shows all of your locations.

How do I get an API token for the AirGradient API?

To obtain an API token, you need to enable API access on the General Settings page of your AirGradient dashboard under the Connectivity tab. Once enabled, you will receive a unique API token that you can use for making API requests.

Do I need to re-enable API access every time?

No, once API access is enabled and you have your API token, you can use it for future API requests without re-enabling.

Is the exported data corrected?

No, the data exported in CSV format or via API in JSON format does not include the corrections applied to the PM, relative humidity, and temperature measurements on your dashboard. The exported data is in its raw form. For more information about the correction algorithms, visit our Correction Algorithms Documentation.

Developed by AirGradient in Collaboration with the UNDP Global Centre Singapore CC-BY-SA