Client for the public AirGradient HTTP API supporting both public locations and private locations using access token authorization.

Installation

npm install airgradient-api

Basic Usage

This client can be used without any additional configuration to query the publicly available data.

import {AirGradientAPI } from 'aigradient-api';

const client = new AirGradientAPI();

// Query current measurements across all publicly available locations.
const measurements = await client.getPublicMeasurements();

// Query current measurements for a specific location.
const glasgowLocationId = 70230;
const measurementsInGlasgow = await client.getPublicMeasurementsForLocation(glasgowLocationId);

// Check the API status.
const isPublicAPIOnline = await client.isUp();

Private Locations

To query private locations associated with a specific account, an access token needs to be configured. For details, see the Configuration section below.

import {AirGradientAPI } from "aigradient-api";

const config = {
    token: "00000000-0000-4000-0000-000000000000",
}

const client = new AirGradientAPI(config);

// Query current measurements across all locations associated with the access token 
const measurements = await client.getMeasurements();

// Query current measurements for a specific location.
const bedroomLocationId = 123456 
const bedroomMeasurements = await client.getMeasurementsForLocation(bedroomLocationId);

// Change LED Mode for a specific location
const updatedMode = await client.setLEDModeForLocation(bedroomLocationId, "co2");

// Read full documentation below for all available methods...

API

The client exposes several methods for querying measurements from the public API, both across publicly available locations and private locations, which require authorization via access token. There are additional methods that allow for device management, such as CO2 sensor calibration, as well as querying API availability status.

Configuration

Additional configuration can be passed to the client to query private locations connected to the AirGradient cloud and adjust the timeout used by the HTTP requests. The access token needed to make requests to private locations can be generated from the AirGradient Dashboard within General Settings > Connectivity > API Access.

interface Config {
    /** Access token used to authorize the requests to private locations. */
    token?: string;
    /** HTTP request timeout in milliseconds. */
    timeout?: number;
}

Usage:

const client = new AirGradientAPI({
    token: "00000000-0000-4000-0000-000000000000", // Needs to be eplaced with your own token
    timeout: 30 * 1000, // 30s
});

Methods

isUp

isUp(): Promise<boolean>

Ping the API endpoint to check its availability status.
Returns true if the API is available, false otherwise.

getPublicMeasurements

getPublicMeasurements(): Promise<Measurements[]>

Get the current measurements of a specific location made public to the world.
Returns an array of current measurements for all public locations.

getPublicMeasurementsForLocation

getPublicMeasurementsForLocation(locationId: LocationId): Promise<Measurements>

Get the current measurements of a specific location made public to the world.

Parameters

• locationId: LocationId
  ID of a location to query the measurements for.

Returns current measurements for a location matching the provided locationId.

getMeasurements

getMeasurements(): Promise<Measurements[]>

Get the current measurements of all locations for a specific place affiliated with the provided access token.
Returns an array of current measurements for all locations within an account.

getMeasurementsForLocation

getMeasurementsForLocation(locationId: LocationId): Promise<Measurements>

Get the current measurements of a specific location within an account associated with the access token.

Parameters

• locationId: LocationId
  ID of a location to query the measurements for.

Returns current measurements for a location matching the provided locationId.

getRawMeasurementsForLocation

getRawMeasurementsForLocation(locationId: LocationId, fromDate?: Date | null, toDate?: Date | null): Promise<Measurements[]>

Get the 200 most recent raw measurements of a specific location within an account associated with the access token, optionally within a specified date range (if provided).

Parameters

• locationId: LocationId
  ID of a location to query the measurements for.
• fromDate: Date (optional)
  date from which the location should be queried for measurements.
• toDate: Date (optional)
  date until which the location should be queried for measurements. When specifying only toDate, the fromDate argument can be set to null.

Returns an array of aggregated measurements for a location matching the provided locationId, as well as fromDate and toDate (if provided).

getPastMeasurementsForLocation

getPastMeasurementsForLocation(locationId: LocationId, fromDate: Date, toDate: Date): Promise<Measurements[]>

Get past measurements of a specific location within an account associated with the access token, within a specified date range (up to 10 days-wide).

Parameters

• locationId: LocationId
  ID of a location to query the measurements for.
• fromDate: Date
  date from which the location should be queried for measurements (range cannot exceed 10 days).
• toDate: Date date until which the location should be queried for measurements (range cannot exceed 10 days).

Returns an array of past measurements for a location matching the provided locationId, as well as fromDate and toDate.

getAggregatedMeasurementsForLocations

getAggregatedMeasurementsForLocations(locationIds: LocationId[], bucketSize: BucketSize): Promise<Measurements[]>

Get aggregated measurements of specific locations within an account associated with the access token, based on the provided bucketSize.

Parameters

• locationIds: LocationId[]
  IDs of locations to query the measurements for.
• bucketSize: BucketSize
  size of the buckets used to aggregate the measurements. This size will determine the date range for which the measurements will be returned.

Depending on the bucketSize used, the measurements will be aggregated for the following durations:

• 5 - 5-minute buckets over the past 24h.
• 15 - 15-minute buckets over the past 48h.
• 30 - 30-minute buckets over the past 48h.
• 60 - 1-hour buckets over the past 7 days.

Returns an array of aggregated measurements for locations matching the provided locationIds for a length of time dependent on the bucket size.

getAggregatedMeasurementsForLocation

getAggregatedMeasurementsForLocation(locationId: LocationId, bucketSize: BucketSize): Promise<Measurements[]>

Convenience wrapper for getAggregatedMeasurementsForLocations. Get aggregated measurements of a specific location within an account associated with the access token, based on the provided bucketSize.

Parameters

• locationId: LocationId
  ID of a location to query the measurements for.
• bucketSize: BucketSize
  size of the buckets used to aggregate the measurements. This size will determine the date range for which the measurements will be returned.

Depending on the bucketSize used, the measurements will be aggregated for the following durations:

• 5 - 5-minute buckets over the past 24h.
• 15 - 15-minute buckets over the past 48h.
• 30 - 30-minute buckets over the past 48h.
• 60 - 1-hour buckets over the past 7 days.

Returns an array of aggregated measurements for location matching the provided locationId for a length of time dependent on the bucket size.

calibrateCO2SensorForLocation

calibrateCO2SensorForLocation(locationId: LocationId): Promise<void>

Trigger a calibration of the CO2 sensors for a specified location within an account associated with the access token.

Parameters

• locationId: LocationId
  ID of a location for which the CO2 sensor calibration will be triggered.

Note: The sensor needs to be in a 400ppm environment when the calibration is performed.

calibrateCO2SensorForDevice

calibrateCO2SensorForLocation(locationId: LocationId): Promise<void>

Trigger a calibration of the CO2 sensor for a device with a specified serial number within an account associated with the access token.

Parameters

• serialNumber: SerialNumber
  Serial number of a specific device for which the calibration will be triggered.

Note: The sensor needs to be in a 400ppm environment when the calibration is performed.

getLEDModeForLocation

getLEDModeForLocation(locationId: LocationId): Promise<LEDMode>

Get the current LED mode for a specified location within an account associated with the access token.

Parameters

• locationId: LocationId
  ID of a location for which the LED mode will be retrieved.

Returns current LEDMode used by the specified location.

getLEDModeForDevice

getLEDModeForLocation(serialNumber: SerialNumber): Promise<LEDMode>

Get the current LED mode for a device with specified serial number within an account associated with the access token.

Parameters

• serialNumber: SerialNumber
  Serial number of a device for which the LED mode will be retrieved.

Returns current LEDMode used by the device with specified serial number.

setLEDModeForLocation

setLEDModeForLocation(locationId: LocationId, ledMode: LEDMode): Promise<LEDMode>

Update the LED mode of a specified location within an account associated with the access token.

Parameters

• locationId: LocationId
  ID of a location for which the LED mode will be updated.
• ledMode: LEDMode
  LED mode which will be set on the location.

Returns the new LEDMode set for the location.

setLEDModeForDevice

setLEDModeForDevice(serialNumber: SerialNumber, ledMode: LEDMode): Promise<LEDMode>

Update the LED mode for a device with the specified serial number within an account associated with the access token.

Parameters

• serialNumber: SerialNumber
  Serial number of the device for which the LED mode will be updated.
• ledMode: LEDMode
  LED mode which will be set on the device.

Returns the new LEDMode set for the device.

Types

Measurements

Measurements returned from the API are either objects or arrays of objects of the following structure:

interface Measurements {
    locationId: LocationId;
    locationName: string;
    locationType: string;
    serialno: number;
    model: string;
    pm01: number;
    pm02: number;
    pm10: number;
    pm01_corrected: number;
    pm02_corrected: number;
    pm10_corrected: number;
    pm003Count: number;
    atmp: number;
    rhum: number;
    rco2: number;
    atmp_corrected: number;
    rhum_corrected: number;
    rco2_corrected: number;
    tvoc: number;
    tvocIndex: number;
    noxIndex: number;
    wifi: number;
    datapoints: number;
    timestamp: string;
    firmwareVersion: string;
    longitude: number;
    latitude: number;
}

• locationId - The unique id of the location (not present for averages).
• locationName - The name of the location as on the AG dashboard (not present for averages).
• locationType - The type of the location as on the AG dashboard ("indoor" or "outdoor").
• serialno - The serial number of the sensor currently linked to the location (not present for averages).
• model - The model identifier of the sensor currently linked to the location (e.g. "I-9PSL", "O-1PST").
• pm01 - The raw PM 1 value in ug/m3.
• pm02 - The raw PM 2.5 value in ug/m3.
• pm10 - The raw PM 10 value in ug/m3.
• pm01_corrected - The PM 1 value with correction algorithms applied in ug/m3.
• pm02_corrected - The PM 2.5 value with correction algorithms applied in ug/m3.
• pm10_corrected - The PM 10 value with correction algorithms applied in ug/m3.
• pm003Count - The number of particles with a diameter beyond 0.3 microns in 1 deciliter of air.
• atmp - The ambient temperature in Celsius.
• rhum - The relative humidity in percentage.
• rco2 - The CO2 value in ppm.
• atmp_corrected - The ambient temperature with correction algorithms applied in Celsius.
• rhum_corrected - The relative humidity with correction algorithms applied in percentage.
• rco2_corrected - The CO2 value with correction algorithms applied in ppm.
• tvoc - The TVOC value in ppb (provided in case that the sensor delivers an absolute value).
• tvocIndex - The value of the TVOC index (sensor model dependent).
• noxIndex - The value of the NOx index, (sensor model dependent).
• wifi - The Wi-Fi signal strength in dBm.
• datapoints - The number of data points (present only for aggregated data).
• timestamp - Timestamp of the measures in ISO 8601 format with UTC offset, e.g. 2022-03-28T12:07:40Z.
• firmwareVersion - The firmware version running on the device (e.g. "9.2.6") (not present for averages).
• longitude - The longitude of the location where the measurement was taken (if available).
• latitude - The latitude of the location where the measurement was taken (if available).

LocationId

LocationId is a type alias for number;

SerialNumber

LocationId is a type alias for string;

BucketSize

Size of the buckets used to aggregate the queried data.

type BucketSize = 5 | 15 | 30 | 60;

Based on the provided bucket size, the measurements will be aggregated for the following durations:

• 5 - 5-minute buckets over the past 24h.
• 15 - 15-minute buckets over the past 48h.
• 30 - 30-minute buckets over the past 48h.
• 60 - 1-hour buckets over the past 7 days.

LEDMode

LED mode used by the device.

type LEDMode = 'co2' | 'pm' | 'off' | 'default';