AirVisual (https://www.airvisual.com) is a website that provides data on air quality around the world. They have an API that we will use to get air quality data to send to a dashboard. We will interact with this API similar to how we did with the weather dashboard.
We’ve already put most of the code together, but you'll need you to make a few adjustments along the way. There is lots of opportunities for expanding on what we've done, too.
To retrieve all of the things we’ve prepared for you, you’ll need to clone the repository from GitHub. GitHub is an awesome service that allows us to store, revise, and manage projects like this. You will want to run this script on a dedicated device. You can use a laptop, Raspberry Pi, or other single board computer. To clone the repository all we need to do is go into our computer's or Pi’s terminal, and type this command:
Once you see this then congrats, you’ve successfully cloned the GitHub Repo and have all of the necessary files to build this project. Let’s move into the new directory. To change directory’s, all you need to do is type “cd” and then type the name of the directory that you wish to go to. In this case, we’ll type:
$ cd airvisual
Once we hit enter, you’ll see that we’re now in the airvisual directory. Let’s type "ls" to see what files we’ve installed. You should seem something as follows:
LICENSE README.md airquality.py
We need some other items before we can edit the code so let's look at the Air Quality API next.
AirVisual has an air quality (AQI) and pollution API that allows up to 10, 000 API calls per month for free. You can sign up for the Community tier. Once you sign up, you can go to My Air and the API tab. It is here that you will find your API keys and documentation on the API.
Click the +New Key button to create our first API access key. For Select Plan, use the dropdown to select Community and click Create. If all goes well you'll see a success message and you can head back to your API dashboard to find your new key information. The Key value (numbers and characters) is what you'll need for this project. If you peruse the API documentation you will see there are multiple kinds of API calls you can make. For this project we want to get the nearest city data based on GPS coordinates. For this call you'll need your longitude, latitude, and API key. Enter those parameters into the call below, put that into an address bar on your browser, and hit enter.
We can easily see now that we have information on location, weather, and pollution. The two values we focus on for this project is the Air Quality Index US (aquis) and Main Pollutant (mainus). The Air Quality Index value tells us what the local air quality value is and how that pertains to your health. The color coded chart is below. The main pollutant tells us what is the main pollutant in the air is for your area (particulate matter, nitrogen oxide, ozone, carbon monoxide, sulfur oxide). These pollutants are typically byproducts of smoke stacks or vehicle emissions.
Now that we know how to use the Air Visual API, the next thing we will need is a dashboard platform to display the data.
We want to stream all of our weather data to a cloud service and have that service turn our data into a nice dashboard. Our data needs a destination so we will use Initial State as that destination.
After you run the curl command, you will see something similar to the following output to the screen:
$ \curl -sSL https://iot.app.initialstate.com -o - | sudo bash
Beginning ISStreamer Python Easy Installation!
This may take a couple minutes to install, grab some coffee :)
But don't forget to come back, I'll have questions later! Found easy_install: setuptools 1.1.6
Found pip: pip 1.5.6 from /Library/Python/2.7/site-packages/pip-1.5.6- py2.7.egg (python 2.7)
pip major version: 1
pip minor version: 5
ISStreamer found, updating...
Requirement already up-to-date:ISStreamer in /Library/Python/2.7/site-packages
Cleaning up... Do you want automagically get an example script? [y/N]
Where do you want to save the example? [default: ./is_example.py] Please select which Initial State app you're using:
2. [NEW!] iot.app.initialstate.com
Enter choice 1 or 2:
Enter iot.app.initialstate.com user name:
Enter iot.app.initialstate.com password:
When prompted to automatically get an example script, type y. This will create a test script that we can run to ensure that we can stream data to Initial State. The next prompt will ask where you want to save the example file. You can either type a custom local path or hit enter to accept the default location. Finally, you'll be asked which Initial State app you are using. If you've recently created an account, select option 2 then enter user name and password. After that installation will be complete
Let’s take a look at the example script that was created.
$ nano is_example.py
On line 15, you will see a line that starts with streamer = Streamer(bucket_.... This lines creates a new data bucket named “Python Stream Example” and is associated with your account. This association happens because of the access_key=”...” parameter on that same line. That long series of letters and numbers is your Initial State account access key. If you go to your Initial State account in your web browser, click on your username in the top right, then go to “my settings”, you will find that same access key at the bottom of the page under “Streaming Access Keys”. Every time you create a data stream, that access key will direct that data stream to your account (so don’t share your key with anyone).
Run the Example
Run the test script to make sure we can create a data stream to your Initial State account. Run the following in your command prompt:
$ python is_example.py
Go back to your Initial State account in your web browser. A new data bucket called “Python Stream Example” should have shown up on the left in your bucket shelf (you may have to refresh the page). Click on this bucket to view the data.
You are now ready to start streaming real data from the AirVisual API.