persair is a python command line client and module for interacting with the PurpleAir API. A set of convenience commands are also available in the nushell based persair.nu script. Typical functions provided include collecting information on specific sensors as well as checking on when a specific sensor last checked in to the Purple API servers. persair also offers convenient sensor-group based operations, collecting data from a set of sensors in the PurpleAir network.
This document describes the Installation and Use of persair.
PurpleAir is a community-owned system of sensors that measure particulate matter in the atmosphere. Sample data is uploaded to PurpleAir in real time and information is shown in a web-based geographic UI, allowing for close-to-realtime monitoring of air quality across the sensor network.
Current and historical data from individual sensors can also be accessed from the PurpleAir API by any client application that is authenticated to the API service. Authentication is performed by using read and write "keys" available from the PurpleAir develop portal. While these authentication keys are freely available, each call to the API carries a "cost" in "tokens" (different calls cost different "amounts"). While PurpleAir provides a number of tokens for free, once exhausted users need to purchase more tokens.
Accessing the API for data from a given sensor requires not only read and write keys, but also somewhat sophisticated knowledge from a user to use a web-based API. In order to simplify this access, persair was created as a terminal-application that provides a simple command-line interface to interacting with the API. In addition to the application itself, several convenience functions are available in a nushell environment.
In this document you will need to use a terminal application to run persair. Commands that you need to type in the terminal are show in source block:
# This is a shell "source" block. In this shell, lines that start with
# a "hash" (#) are considered comments and are for illustrative purposes.
# Any shell "commands" that should be typed into a terminal will appear
# in a line of their own without a leading hash character. In the next line,
# the "someCommand" is command to type, the "--withAFlag" is a command line
# flag, and the "value" the value for that flag:
someCommand --withAFlag valueSeveral installation steps are required to use persair, typical of most command line python applications. Usually these assume a "UNIX" (Linux or macOS) operating system, however instructions/pointers for Windows systems are also provided. The steps are:
While not required, it is also highly suggested to also install nushell as the command line interpreter in your terminal. There are several convenience scripts offered by this repository that leverage the excellent JSON parsing and presentation abilities of nushell.
persair will faithfully return the reponses from the PurpleAIR API without any embellishments. This might not always be immediately useful. For instance, dates are returned as UNIX epochs, not as more standard date strings. It it highly recommended to use the companion nushell documentation for more human friendly returns!
If your sensors have all been placed into a group with id, say 1700, you can get a list of all sensor indices with
# Remember to set the read/write keys in the environment first!
persair --sensorsInGroupList --usingGroupID 1700This will return a JSON object with all the sensor indices in the terminal.