AirGradient API

AirGradient offers APIs (application programming interfaces). An API is essentially a bridge that lets different software systems communicate with each other. In this case, it enables you to pull data from your AirGradient monitors into your own applications, websites, or data dashboards—making the data more useful and accessible for your specific needs. This documentation is intended for software developers and just an optional step. Using the API is not required to gain access to your air quality data. More accessible ways to access and download data for non-developers are discussed in O6: Data Download and Export.

AirGradient supports two types of APIs: a Public API for data hosted on the AirGradient cloud, and a Local API for accessing data directly from the device over a local network. This gives users flexibility depending on whether they want to use cloud-based solutions or prefer local access for privacy or offline use.

In this document, we will cover the basics of AirGradient’s APIs. Please note that we won’t dive into advanced implementation details, and a developer with technical experience may be needed to make full use of the APIs.

1. Why should I use the API?

Using the AirGradient API can help you to efficiently share your air quality data with your community . It allows you to automatically get your hyperlocal air quality readings onto websites, apps, or alert systems without constant manual downloading of data. This makes the invisible visible, empowering residents with timely information and providing solid evidence for advocacy and demanding change.

Here are some ways that you might want to make use of the API:

• Localised Health Warnings: Simple alert systems (SMS, app notifications) warn residents, schools, or clinics about poor air quality spikes detected by nearby monitors.
• Community Advocacy Tools: Automatically feed local monitor data into online dashboards or reports shared with policymakers, regulators, and news outlets to highlight pollution hotspots and demand action.
• Tenant/Resident Information Boards: Displaying real-time local air quality readings in community centers, libraries, or apartment building lobbies.
• “Safe Route” Planners for Walking/Biking: Suggesting routes that avoid areas currently showing higher pollution based on the community’s monitors.
• Correlating Pollution with Local Activities: Allow residents to see if pollution levels (from their monitor) rise during events like high traffic times, nearby industrial operations, or specific weather conditions.
• Evidence for Grant Applications: Use the easily accessible, organised historical data from the API to demonstrate the need for funding for air filters, green spaces, or health programs.
• Educational Displays in Schools: Displaying students’ real-time data from a monitor possibly located right on their school grounds connects environmental science to their immediate surroundings.

2. AirGradient API Features

Documentation for the API can be found on Swagger. At a basic level, the API will allow you to pull information on every metric that the monitor measures, meaning you can pull PM_2.5, temperature, or even carbon dioxide information from your AirGradient monitors.

Above and beyond this, you can also pull data from any outdoor AirGradient monitor worldwide, as long as it’s set to public view. This means that you can not only pull data from your own monitors with this method, but also from thousands of other monitors globally. Importantly, you can also pull limited historical data from any of these monitors through the place ID.

3. Using the AirGradient Public API

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. Accessing Monitor Data via the Local API

Along with our public API (which can be accessed from any location), we offer a local API which can only be accessed by devices on the same WiFi network as the AirGradient monitor in question. This allows organisations that want to run a monitor or network within their local network to access data and configuration settings from local devices.

For more information about AirGradient local API, please go to local-server documentation.

1. Prepare environment: Make sure the AirGradient monitor is connected to WiFi and within the same network as the device that wants to retrieve the data.

2. Retrieve measurement data: To retrieve the latest measurements, open browser and access below URL with format:
   

     http://airgradient\_**{{SERIAL\_NUMBER}}**.local/measures/current
   

   Be sure to change {{SERIAL_NUMBER}} to the serial number (you can find this on the back of your monitor) of the target monitor, so it will be like:

     http://airgradient\_aaaaaaaaaaaa.local/measures/current
   

   

3. Retrieve local configuration: To retrieve local configuration, same as point 2 but the URL format as follow:
   

     http://airgradient\_**{{SERIAL\_NUMBER}}**.local/config
   

   

4. 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.

5. Frequently Asked Questions (FAQs)

If you run into any issues or are looking for further answers, please read the FAQs below.

What is the AirGradient API?

The AirGradient API is a tool provided by AirGradient that allows users and organisations to automatically pull air quality data from AirGradient’s servers. It enables you to integrate data from your monitors (and other public monitors) into your own applications or websites.

What kind of data can I get through the API?

You can pull information for every metric the AirGradient monitor measures, such as PM_2.5, temperature, and carbon dioxide. You can also access limited historical data for monitors.

How do I get started using the API?

First, you need to obtain an API Token by enabling API access in your AirGradient dashboard’s General Settings (under Connectivity). You may also need the specific Location ID for your monitor(s), found on the Locations Administration page. You then use this token (and Location ID if needed) when making data requests, following the guidelines in the Swagger Documentation.

Do I need technical skills to use the API?

This document covers the basics of accessing the API. However, implementing the data you receive into a custom application or website likely requires a developer with experience. This document does not cover those advanced implementation aspects.

In what format does the API provide the data in?

The API returns the requested data in JSON format, which is a standard machine-readable format suitable for use in applications.

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