Are you also looking for Node version ?
All formulas, constraints, and messages use in this project follows US EPA AQI Calculation Guideline and Regulations (which includes breakpoint table and calculation formulas) . Since each country issues different AQI calculation methods, using this package might be inappropriate, consider your usage.
This project is intended to community target for free use. The author is not associated with USA government, nor United States Environmental Protection Agency (a.k.a US EPA)
- Calculate AQI from raw concentration
- The result from calculation includes Air Quality Index, Category, Color, Sensitive Groups of the pollutant and the corresponding Health Effects Statements and Cautionary Statements messages.
- Support NowCast Concentration
- You need to get messages in another language ? AQI Calculator now allows customizable messages at your own need.
| Pollutant | Scientific name | Unit of Measurement | Sensitive Groups | Regular Calculation Support | NowCast Support | Health Effects Statements | Cautionary Statements |
|---|---|---|---|---|---|---|---|
| PM10 | 10 μm Particle Pollutant | μg/m3 | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
| PM2.5 | 2.5 μm Particle Pollutant | μg/m3 | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
| O3 | Ozone | ppb | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
| CO | Carbon Monoxide | ppb | ✔️ | ✔️ | ❌ | ✔️ | ✔️ |
| SO2 | Sulfur Dioxide | ppb | ✔️ | ✔️ | ❌ | ✔️ | ✔️ |
| NO2 | Nitrogen Dioxide | ppb | ✔️ | ✔️ | ❌ | ✔️ | ✔️ |
If you prefer to use this library as a standalone REST API app, see AQI Calculator as a standalone app
<!-- https://mvnrepository.com/artifact/com.github.thanglequoc/aqi-calculator -->
<dependency>
<groupId>com.github.thanglequoc</groupId>
<artifactId>aqi-calculator</artifactId>
<version>1.3.2</version>
</dependency>
// https://mvnrepository.com/artifact/com.github.thanglequoc/aqi-calculator
implementation group: 'com.github.thanglequoc', name: 'aqi-calculator', version: '1.3.2'
Or for other build tools like SBT, Ivy,.. you may find it on Maven Central Repository
Grab the target jar in target-jar folder and add the jar to your project.
AQICalculator calculator = AQICalculator.getAQICalculatorInstance();
AQIResult result = calculator.getAQI(Pollutant.PM10, 99);
Now AQIResult store all the related information that you might need, query them by the following methods
- The Air Quality Index (AQI)
result.getAQI();
73
- The Concentration
result.getConcentration();
For NowCast calculation, this will be the NowCast Concentration
99.0
- The AQI Category
result.getCategory();
Moderate
- The color of this index
result.getColor()
Yellow
- The meaning of of this index
result.getMeaning()
Air quality is acceptable; however, for some pollutants there may be a moderate health concern for a very small number of people who are unusually sensitive to air pollution
- The sensitive groups of this pollutant
result.getSensitiveGroups()
People with respiratory disease are the group most at risk
- The health effects statements
result.getHealthEffectsStatements();
Respiratory symptoms possible in unusually sensitive individuals; possible aggravation of heart or lung disease in people with cardiopulmonary disease and older adults
- The cautionary statements
result.getCautionaryStatements();
Unusually sensitive people should consider reducing prolonged or heavy exertion
/* Example Data for NowCast PM10 12h period - 64, 63, 72, 77, 65, 61, 70, 71, 64, 57, 58, 64 */
AQICalculator calculator = AQICalculator.getAQICalculatorInstance();
double[] data = { 64, 63, 72, 77, 65, 61, 70, 71, 64, 57, 58, 64 };
AQIResult result = calculator.getNowCastAQI(Pollutant.PM10, data);
System.out.println(result.getAQI());
57
The first value in the array is the avg value in the current hour, and each next element in the array represent the previous data of the hour before current hour.
If the hour doesn't have data, replace missing data in the hour with -1
| Hour | Avg Concentration |
|---|---|
| 14 | 64 ppb |
| 13 | 63 ppb |
| 12 | ---- |
| 11 | 77 ppb |
| 10 | 65 ppb |
| 9 | ---- |
| 8 | 70 ppb |
| 7 | 71 ppb |
| 6 | ---- |
| 5 | 57 ppb |
| 4 | 58 ppb |
| 3 | 64 ppb |
Presume that you want to calculate NowCast AQI for PM10 at 14, the data array should be
double[] data = { 64, 63, -1, 77, 65, -1, 70, 71, -1, 57, 58, 64 };`
AQIResult result = calculator.getNowCastAQI(Pollutant.PM10, data);
result.getAQI();
56
The default text from AQI result is in English. However, you can easily override these messages in your own language. Just download the template files and make change on your own
Allowed customized messages resources:
- General Messages
- Sensitive Groups
- Specific Messages
Example: Override with custom AQI message in German language. Simply done by enable custom message mode, and provide any of the override files path from your project classpath.
AQICalculator calculator = AQICalculator.getAQICalculatorInstance();
AQICustomSettings mySettings = new AQICustomSettings()
.withCustomMessagesMode(true)
.withGeneralMessageResourcePath("AQIResource/custom-aqi-general-messages_de.json")
.withSensitiveGroupsResourcePath("AQIResource/custom-aqi-sensitive-groups_de.json")
.withSpecificMessageResourcePath("AQIResource/custom-aqi-specific-messages_de.json");
calculator.applyCustomSettings(mySettings);
AQIResult aqiResult = calculator.getAQI(Pollutant.PM10, 99);
System.out.println(aqiResult.getCategory());
System.out.println(aqiResult.getMeaning());
System.out.println(aqiResult.getSensitiveGroups());
System.out.println(aqiResult.getHealthEffectsStatements());
System.out.println(aqiResult.getCautionaryStatements());
Outcome
Mäßig
Luftqualität ist akzeptabel; Bei einigen Schadstoffen kann es jedoch zu einer mäßigen Gesundheitsgefährdung für eine sehr kleine Anzahl von Personen kommen, die ungewöhnlich empfindlich auf Luftverschmutzung reagieren
Am stärksten gefährdet sind Menschen mit Atemwegserkrankungen
Atmungssymptome bei ungewöhnlich empfindlichen Personen möglich; Mögliche Verschlimmerung von Herz- oder Lungenerkrankungen bei Personen mit kardiopulmonaler Erkrankung und älteren Erwachsenen
Ungewöhnlich sensible Menschen sollten in Betracht ziehen, längere oder schwere Belastungen zu reduzieren
I'm not familiar with German, these messages is just the copy-paste result from Google Translate 🐑
General Messages contains the category, meaning and color
[{
"index": {
"min": 0,
"max": 50
},
"category": "<<Text in your language>>",
"meaning": "<<Text in your language>>",
"color": "<<Text in your language>>"
}]
Download General Messages Resource File and custom it on your own. Then set this file path with withGeneralMessageResourcePath(<path_to_your_file>)
AQICustomSettings mySettings = new AQICustomSettings()
.withCustomMessagesMode(true)
.withGeneralMessageResourcePath("AQIResource/custom-aqi-general-messages_de.json");
calculator.applyCustomSettings(mySettings);
Sensitive Groups File contains list of pollutant's sensitive groups
[{
"code": "PM2.5",
"sensitiveGroups": "<<Text in your language>>"
}]
Download Sensitive Groups Resource File and custom it on your own. Then set this file path with withSensitiveGroupsResourcePath(<path_to_your_file>)
AQICustomSettings mySettings = new AQICustomSettings()
.withCustomMessagesMode(true)
.withSensitiveGroupsResourcePath("AQIResource/custom-aqi-sensitive-groups_de.json");
calculator.applyCustomSettings(mySettings);
Specific Messages contains Health Effects Statements and Cautionary Statements for each pollutant and each specific quality level
[{
"code": "PM2.5",
"aqiLevel": [{
"index": {
"min": 0,
"max": 50
},
"category": "<<Text in your own language>>",
"healthEffectsStatements": "<<Text in your own language>>",
"cautionaryStatements": "<<Text in your own language>>"
}]
}]
Download Specific Messages Resource File and custom it on your own. Then set this file path with withSpecificMessageResourcePath(<path_to_your_file>)
AQICustomSettings mySettings = new AQICustomSettings()
.withCustomMessagesMode(true)
.withSpecificMessageResourcePath("AQIResource/custom-aqi-specific-messages_de.json");
calculator.applyCustomSettings(mySettings);
Reset the calculator to default messages path settings with calculator.resetDefaultSettings();
There is a AQI Calculator Spring Boot project built upon this library to make it easy to get it up and running
Fear of Java, Spring Boot, or maybe you're just too lazy to install them.
With Docker, it's super easy to get the container up and running without installing Java on your local machine. You don't need to know Java or Spring
Give it a go:
docker pull thanglequoc/aqi-calculator-spring-boot:latest
The container application port is 8080, you will need to map your host port to the port 8080 of the container
Run the container with a specified port on your machine (e.g: 8080) to the application port 8080
docker run --name=aqi-calculator -p 8080:8080 thanglequoc/aqi-calculator-spring-boot
Checkout this AQI Calculator Spring Boot repository and run it
See the document of AQI Calculator Spring Boot repo for API usage
The AQI is the highest value calculated for each pollutant as follows:
- Identify the highest concentration among all of the monitors within each reporting area and truncate as follows:
- Using US EPA AQI Breakpoint, find the two breakpoints that contain the concentration.
- Using AQI Equation , calculate the index.
- Round the index to the nearest integer.
The concentration of PM10, PM2.5 is so dynamic since wind can completely clean the air in less than 30 minutes, or a wildfire can raise the concentration with a very fast rate in an hour. So NowCast is introduced, it mainly focus on detect the average changing of the period hour and perform counter balancing.
To compute a valid NowCast, you must have at least two of the most recent 3 hours
Air Quality Index (AQI) Basics
Air Now AQI Calculator: Concentration to AQI
Daily and Hourly AQI - PM2.5 and PM10
US EPA AQI Technical Assistance Document. I am have no idea why the section Health Effects Statements section is not presented in their latest document guideline. I managed to kept the one in 2016 that have this section
Demonstration images for NowCast in this tutorial are from US EPA NowCast Overview document
Without these great contribution from these guys, this repository might not be as it is today. I would like to express my gratitude to
Marcus Hylton - US EPA Airnow Specialist
Code Contributors
Proudly powered by IntelliJ IDEA from JetBrains for open source project
