Purple Air Data

PurpleAir has recently enacted billing for accessing data. The costs are calculated on a points based per call. The point costs are available at https://community.purpleair.com/t/api-pricing/4523. If you are accessing your own sensors contact them at contact@purpleair.com to enable no cost access.

The points per call breakdown is available at https://develop.purpleair.com/pricing. Your cost depends on the frequency (as described below) of the calls and what is being accessed. Each Purple Air entry can be configured to access either the default fields, short fields or all fields. So roughly speaking, for the short fields this is 8 fields @ 2 points/field plus 1 point for the call = 17 points. if you collect the data every 15 minutes that is ~49000 points per month. From the Purple Air pricing of 100,000 points/$1 USD this is 50 cents per sensor per month.

If you have existing Purple Air sensors in your RAMADDA then currently the default field list is the "short" list. You can change this to use the "default" list which is fewer fields and thus less cost. You can also change the frequency of how often the data is fetched. And finally, you can inactivate individual Purple Air entries by editing the entry and setting Active=false.

Sensor data from Purple Air sensors can be read and displayed in RAMADDA. The data is provided by Purple Air through their API and requires an API key. To get the key send a request to contact@purpleair.com. Once you have the key add a property to your repository.properties file (in the RAMADDA home directory) and restart your RAMADDA.

purpleair.api.key=key here

The default frequency for fetching data is every 15 minutes. This can be changed with a property in repository.properties:

purpleair.frequency=15

With the API key specified RAMADDA will periodically access the API for each Purple Air entry you have created and append the current data to a local CSV file in RAMADDA. This file can be downloaded from the sensor entry page. Over time these files can grow to be quite large (depending on the API fetch frequency). The default display only shows the most recent 20000 records. You can clear out the entire file for an sensor entry through the Clear File menu item.

Once the API key is configured you can create new Purple Air Sensor entries. Go to the RAMADDA folder you want to add the entries to and from the entry popup menu select "Pick a Type...". From the list under Geoscience/Point Data select "Purple Air Sensor". The only field you need to specify is the Sensor ID. The ID is a numeric ID and should be able to be accessed through your Purple Air account.

Alternatively, you can access IDs for any public sensor from the map at https://map.purpleair.com/. Click on the sensor of interest and you should see the below popup. Hover over the "Get This widget" link to see the ID in the embed HTML, e.g. 112686, or in the Download Data link.

When a new Purple Air Sensor entry is created RAMADDA will fetch the metadata for the sensor, e.g. name, location, model, etc. If the sensor is a private sensor you can enter the private key when creating the entry. The private key is available through your Purple Air account. You can also add your private key as a RAMADDA property in a .properties file on your server. Specify your the property ID as the private key in the entry. For example, if you had a private key "some_private_key" then, in a repository.properties file enter:

myprivatekey=some_private_key

The name of the property, e.g., "myprivatekey", is arbitrary. Now, when you create the Purple Air entry in RAMADDA in the private key field just entry "myprivatekey".

The default display for a Purple Air Sensor entry is shown below. Note, initially there is no data but over time the data will be fetched from the API.

If you want to stop fetching then, go the Edit page for the entry and set Active to No.

The Purple Air API provides a large number of sensor fields. The Purple Air RAMADDA entry allows you to select one of two sets of fields - Default, Short or All.

The default fields are:

humidity,temperature,pressure,voc,ozone1,pm1.0,pm2.5,pm10.0

The short fields are:

  humidity,temperature,pressure,voc,ozone1,pm1.0,pm2.5,pm10.0
  0.3_um_count,0.5_um_count,1.0_um_count,2.5_um_count,5.0_um_count,10.0_um_count

and the all fields include all of the available fields:

humidity, humidity_a, humidity_b
temperature, temperature_a, temperature_b
pressure, pressure_a, pressure_b
voc, voc_a, voc_b
ozone1
analog_input
pm1.0, pm1.0_a, pm1.0_b, pm1.0_atm, pm1.0_atm_a, pm1.0_atm_b
pm1.0_cf_1, pm1.0_cf_1_a, pm1.0_cf_1_b
pm2.5_alt, pm2.5_alt_a, pm2.5_alt_b, pm2.5, pm2.5_a, pm2.5_b
pm2.5_atm, pm2.5_atm_a, pm2.5_atm_b, pm2.5_cf_1, pm2.5_cf_1_a
pm2.5_cf_1_b,pm2.5_10minute, pm2.5_10minute_a, pm2.5_10minute_b
pm2.5_30minute, pm2.5_30minute_a, pm2.5_30minute_b, pm2.5_60minute
pm2.5_60minute_a, pm2.5_60minute_b, pm2.5_6hour, pm2.5_6hour_a
pm2.5_6hour_b, pm2.5_24hour, pm2.5_24hour_a, pm2.5_24hour_b
pm2.5_1week, pm2.5_1week_a, pm2.5_1week_b,pm10.0, pm10.0_a
pm10.0_b, pm10.0_atm, pm10.0_atm_a, pm10.0_atm_b, pm10.0_cf_1
pm10.0_cf_1_a, pm10.0_cf_1_b
scattering_coefficient, scattering_coefficient_a, scattering_coefficient_b
deciviews, deciviews_a, deciviews_b
visual_range, visual_range_a, visual_range_b
0.3_um_count, 0.3_um_count_a, 0.3_um_count_b, 
0.5_um_count, 0.5_um_count_a, 0.5_um_count_b
1.0_um_count, 1.0_um_count_a, 1.0_um_count_b
2.5_um_count, 2.5_um_count_a, 2.5_um_count_b
5.0_um_count, 5.0_um_count_a, 5.0_um_count_b
10.0_um_count 10.0_um_count_a, 10.0_um_count_b

There are 2 ways to show a map of Purple Air sensor entries. Assuming you have a folder that holds the entries of interest (e.g., Test Purple Air) the default display of that folder will look like: To have the folder just show a map go and edit the folder, click on the "wiki display" checkbox, and enter the below wiki text. This will give a map view of the children entries:

A richer map display can be created with the Integrated Map Data Viewer (IMDV) display component. In another folder go to the File->Pick a Type... menu and look for "Integrated Map Data" under the GIS Data list.

Once created select "Multi Entry" under the New menu: Choose the folder that holds your Purple Air sensor entries. You should end up with something like: Click on the settings icon () to bring up the settings dialog for this multi entry, select "Show entry data" and press OK The Purple Air entries in the map will now show a color-coded circle with the latest PM2.5 measure: You can also annotate the IMDV map and add other instruments, map layers, etc. For example, below shows a number of individual Purple Air sensors and CR1000 data logger entries. These are created with the New-&>Entry Marker menu. The color bar at the bottom is created with wiki text in the Footer property for the IMDV map. Open the main Properties dialog with IMDV File->Properties menu. Add the below wiki text to the Bottom Wiki Text field: