I woke up one morning in January 2020 and discovered that the air quality in Melbourne had dropped to hazardous levels from bushfire smoke. This hazardous air quality was extremely concerning to my wife and I with our newborn.
I wanted to receive an SMS message whenever PM2.5 levels exceeded 300 so that we could be more alert and take action (wear a mask, try to filter the air). But I didn't have any air quality sensors at home.
Air quality data from the EPA AirWatch API
While looking at the air quality page for a nearby suburb on the EPA Victoria website, I noticed "Connect to our developer portal". I signed up and soon discovered that the EPA have an AirWatch API. Awesome!
There were three things that I needed to do to get air quality info for a nearby suburb:
- Sign up and get an API Key via the EPA Developer Portal
- Read the AirWatch API documentation and figure out what the Site ID is for a nearby suburb.
- Create a script to call the AirWatch API and get air quality information for a particular site.
SMS alert via Telstra Messaging API
Now I don't want to visit the EPA website every day to see the current reading in my area, and other channels like email could easily be missed. So for this critical alert I wanted to go with SMS.
For the past few years I've been sending SMS messages using the free tier of the Telstra Messaging API for random projects like this. Your first 100 messages are free!
I found the documentation and error messages pretty helpful for getting my home projects set up quickly and easily.
Remember that when you are using the free trial to test your project, you need to register your own mobile as a "B Number" first, as the free trial version allows you to send SMS to max 5 other numbers. I used the Postman collection to do that as a once-off.
Air Quality Alert
Okay, so with access to the EPA AirWatch API and the Telstra Messaging API I had:
- Air quality data
- A way to send SMS messages
Now I needed to set up an automated script to pull the Air Quality data every hour, and compare that to the 300µg/m³ threshold I'd set.
I whipped up a script with bash, curl and scheduled it to run via crontab on my Linux server. But after this initial kneejerk reaction to hazardous air quality, I decided to rewrite the script in Python.
The threshold can be configured in check_air_quality.config.json. I initially used a low threshold of around 50 while testing but I was getting too many SMS alerts so I raised it to 100. 100 isn't great, but it's pretty alarming when PM2.5 exceeds 300. I'd suggest using a threshold that you're comfortable with.
I scheduled the script to run on my Linux server every hour at 20 minutes past the hour using a cron job entry:
20 * * * * /home/user/air_quality_alert/check_air_quality.py >> /home/user/air_quality_alert/check_air_quality.log 2>&1
The script is up on my GitHub with detailed instructions, feel free to fork it and adapt it for yourself!
So now when the EPA AirWatch registers PM2.5 levels exceeding 300µg/m³ I'll be the first to know! Finger crossed we won't see this message this year, but better to be safe than sorry.
This is what the script does in a nutshell:
- Submit a GET request to https://gateway.api.epa.vic.gov.au/environmentMonitoring/v1/sites/ to get Site Health Advice for Box Hill
- Grab the average value for PM2.5 out of the Site Health Advice
- If the average value for PM2.5 exceeds my threshold (300µg/m³ ) then:
- Get an access token for the Telstra Messaging API by submitting a POST request to https://tapi.telstra.com/v2/oauth/token
- Get a Telstra Virtual Number to send an SMS by submitting a POST request to https://tapi.telstra.com/v2/messages/provisioning/subscriptions
- Send an SMS by submitting a POST request to https://tapi.telstra.com/v2/messages/sms
Here's what the SMS alerts looks like coming from my Telstra Virtual Mobile Number (with some test data):
As you can see, air quality was shifting between Very Poor and Hazardous around the middle of January 2020.
Python all the things!
It's amazing to see Python being embraced at school by organisation like Code Club Australia and now calculators are supporting this language!
(my daughter Evelyn and I are already tinkering with air purifiers!)
I learnt how to code with TI-BASIC on a TI-83 Plus graphing calculator in High School. It came with a thick reference manual. My maths teacher gave me a Borland BASIC book to nurture my curiosity and encourage me to port programs from one BASIC language to another.
With more and more APIs being made accessible, people can start whipping up solutions quickly in Python to satisfy their needs. Python seems to be a modern day Swiss Army Knife of coding!
My next project will involve using a cheap PMS7003 air quality sensor to get our own local air quality measurements at home.
If you have questions about this project, specifically for integrating with the Telstra Messaging API, please post on their support forum: https://dev.telstra.com/forums/messaging-api-forum