Easily convert between AQIs (US, CN...) and raw values (ug/m3, ppm)

Usage no npm install needed!

<script type="module">
  import shootismokeConvert from 'https://cdn.skypack.dev/@shootismoke/convert';


npm (scoped) dependencies Status Maintainability Test Coverage


A library to convert between various Air Quality Indexes (US, CN...) and their equivalent in pollutant concentration (µg/m³, ppm, ppb).

Supported Air Quality Indexes

AQI AQI Code1 Pollutants Resources
AQI (US) usaEpa co, no2, o3, pm10, pm25, so2 US Environmental Protection Agency (EPA) [link]
AQI (CN) chnMep co, no2, o3, pm10, pm25, so2 China Ministry of Environmental Protection (MEP) [link]

We also plan to support other AQIs in the future, see issue #15 if you want to help.

1: We use the same AQI code as Breezometer, the only difference is that the code here is camelCase, because JavaScript likes camelCase.

⚡ Get Started

Install the package:

yarn install @shootismoke/convert

The package mainly exports the convert function.

convert(pollutant, from, to, value)

The function can convert, for any pollutant:

  • from a raw concentration to a supported AQI
  • from a supported AQI to a raw concentration
  • from a supported AQI to another AQI


  • pollutant: Pollutant: One of the supported pollutants, see them.
  • from: AqiCode | 'raw': An AQI code or the 'raw' string
  • to: AqiCode | 'raw': An AQI code or the 'raw' string
  • value: number: The value to convert
import { convert, getPollutantMeta } from '@shootismoke/convert';

// Convert PM2.5 from usaEpa AQI to raw concentration
const raw = convert('pm25', 'usaEpa', 'raw', 57);
console.log(raw); // 15

console.log(getPollutantMeta('pm25').preferredUnit); // "µg/m³", which is the unit of the value 15 above

// Convert PM2.5 from raw concentration to usaEPA AQI
const aqi = convert('pm25', 'raw', 'usaEpa', 15);
console.log(aqi); // 57

Supported Pollutants

The pollutants the AQIs apply to are: 'bc' | 'co' | 'c6h6' | 'ox' | 'nh3' | 'nmhc' | 'no' | 'nox' | 'no2' | 'o3' | 'pm10' | 'pm25' | 'so2' | 'trs'. Check this file to see the metadata for each pollutant (full name, unit...).

Full Documentation

See the API reference documentation.

:raising_hand: Contribute

  1. Fork the repo
  2. Make your changes in your own fork
  3. Make sure yarn lint and yarn test pass
  4. Create a Pull Request on this repo


Look out for *.spec.ts in the codebase. Run:

yarn test

:newspaper: License

GPL-3.0. See LICENSE file for more information.