API History Fields Descriptions

Data API
1

This list contains definitions for fields that can be used with the historical API. The left side of the table is the name of the field and the right side contains its description.

For any PurpleAir sensors with two laser counters, one laser counter is referred to as Channel A, and the other is referred to as Channel B. These are denoted in the fields with “_a” and “_b” suffixes.

Name Description
sensor_index The sensor’s index. Can be used to add a sensor to a group or view it’s details. This field is included by default in every GET request and should not be added to the fields.
name The name given to the sensor from the registration form and used on the PA map (this field does not currently work with historical endpoints).
last_seen The UNIX time stamp of the last time the server received data from the device (this field does not currently work with historical endpoints).
hardware The sensors and other hardware that was detected by the firmware.
latitude The latitude position value for the sensor (this field does not currently work with historical endpoints).
longitude The longitude position value for the sensor (this field does not currently work with historical endpoints).
altitude The altitude for the sensor’s location in feet (this field does not currently work with historical endpoints).
firmware_version The last known firmware version on the device.
rssi The WiFi signal strength.
uptime The time in minutes since the firmware started as last reported by the sensor.
pa_latency The time taken to send data to the PurpleAir servers in milliseconds.
memory Free HEAP memory in Kb.
humidity Returns humidity average for channel A and B. Relative humidity inside of the sensor housing (%). On average, this is 4% lower than ambient conditions. Null if not equipped.
humidity_a Returns humidity data for channel A.
humidity_b Returns humidity data for channel B.
temperature Returns temperature average for channel A and B. Temperature inside of the sensor housing (F). On average, this is 8F higher than ambient conditions. Null if not equipped.
temperature_a Returns temperature data for channel A.
temperature_b Returns temperature data for channel B.
pressure Returns pressure average for channel A and B. Current pressure in Millibars.
pressure_a Returns pressure data for channel A.
pressure_b Returns pressure data for channel B.
voc Returns VOC average for channel A and B. VOC concentration (IAQ) in Bosch static iaq units as per BME680 spec sheet, EXPERIMENTAL. Null if not equipped.
voc_a Returns VOC data for channel A.
voc_b Returns VOC data for channel B.
analog_input If anything is connected to it, the analog voltage on ADC input of the PurpleAir sensor control board.
pm1.0_atm Returns ATM variant average for channel A and B but excluding downgraded channels. Estimated mass concentration PM1 (ug/m3). PM1 are extremely fine particulates with a diameter of fewer than 1 microns.
pm1.0_atm_a Returns ATM variant for channel A.
pm1.0_atm_b Returns ATM variant for channel B.
pm1.0_cf_1 Returns CF=1 variant average for channel A and B but excluding downgraded channels.
pm1.0_cf_1_a Returns CF=1 variant for channel A.
pm1.0_cf_1_b Returns CF=1 variant for channel B.
pm2.5_alt Returns average ALT variant for channel A and B but excluding downgraded channels.The ALT Variant estimated mass concentration PM2.5 (ug/m3) is derived from the particle counts. PM2.5 are fine particulates with a diameter of fewer than 2.5 microns.
pm2.5_alt_a Returns ALT variant for channel A.
pm2.5_alt_b Returns ALT variant for channel B.
pm2.5_atm Returns ATM variant average for channel A and B but excluding downgraded channels. Estimated mass concentration PM2.5 (ug/m3). PM2.5 are fine particulates with a diameter of fewer than 2.5 microns.
pm2.5_atm_a Returns ATM variant for channel A.
pm2.5_atm_b Returns ATM variant for channel B.
pm2.5_cf_1 Returns CF=1 variant average for channel A and B but excluding downgraded channels.
pm2.5_cf_1_a Returns CF=1 variant for channel A.
pm2.5_cf_1_b Returns CF=1 variant for channel B.
pm10.0_atm Returns ATM variant average for channel A and B but excluding downgraded channels. Estimated mass concentration PM10 (ug/m3). PM10 are coarse particulates with a diameter of fewer than 10 microns.
pm10.0_atm_a Returns ATM variant for channel A.
pm10.0_atm_b Returns ATM variant for channel B.
pm10.0_cf_1 Returns CF=1 variant average for channel A and B but excluding downgraded channels.
pm10.0_cf_1_a Returns CF=1 variant for channel A.
pm10.0_cf_1_b Returns CF=1 variant for channel B.
scattering_coefficient Returns average for channel A and B. Fine Particulate Light Scattering: The interaction of light with fine particulate matter causing the light to be redirected from its path. When looking at a scene, haze is partially due to light emanating from the scenic elements being scattered out of the sight path and random light (air light) being scattering into the sight path. See, http://vista.cira.colostate.edu/Improve/visibility-basics/.
scattering_coefficient_a Returns scattering coefficient data for channel A.
scattering_coefficient_b Returns scattering coefficient data for channel B.
deciviews Returns deciviews average for channel A and B. A haze index related to light scattering and extinction that is approximately linearly related to human perception of the haze. See http://vista.cira.colostate.edu/Improve/visibility-basics/.
deciviews_a Returns deciviews data for channel A.
deciviews_b Returns deciviews data for channel B.
visual_range Returns average for channel A and B. Often referred to as visibility, visual range is the distance from the observer that a large dark object, e.g. a mountain top or large building, just disappears from view.
visual_range_a Returns visual range data for channel A.
visual_range_b Returns visual range data for channel B.
0.3_um_count Returns average particle count for channel A and B but excluding downgraded channels. Count concentration (particles/100ml) of all particles greater than 0.3 µm diameter.
0.3_um_count_a Returns particle count for channel A.
0.3_um_count_b Returns particle count for channel B.
0.5_um_count Returns average particle count for channel A and B but excluding downgraded channels. Count concentration (particles/100ml) of all particles greater than 0.5 µm diameter.
0.5_um_count_a Returns particle count for channel A.
0.5_um_count_b Returns particle count for channel B.
1.0_um_count Returns average particle count for channel A and B but excluding downgraded channels. Count concentration (particles/100ml) of all particles greater than 1.0 µm diameter.
1.0_um_count_a Returns particle count for channel A.
1.0_um_count_b Returns particle count for channel B.
2.5_um_count Returns average particle count for channel A and B but excluding downgraded channels. Count concentration (particles/100ml) of all particles greater than 2.5 µm diameter.
2.5_um_count_a Returns particle count for channel A.
2.5_um_count_b Returns particle count for channel B.
5.0_um_count Returns average particle count for channel A and B but excluding downgraded channels. Count concentration (particles/100ml) of all particles greater than 5.0 µm diameter.
5.0_um_count_a Returns particle count for channel A.
5.0_um_count_b Returns particle count for channel B.
10.0_um_count Returns average particle count for channel A and B but excluding downgraded channels. Count concentration (particles/100ml) of all particles greater than 10.0 µm diameter.
10.0_um_count_a Returns particle count for channel A.
10.0_um_count_b Returns particle count for channel B.
3 Likes
2

The definition of humidity includes a serious underestimate of the humidity inside the monitor compared to ambient RH.

humidity Returns humidity average for channel A and B. Relative humidity inside of the sensor housing (%). On average, this is 4% lower than ambient conditions. Null if not equipped.

I believe the true difference is on the order of 15%. If desired, I can provide evidence .

1 Like
3

Correction: The “underestimate” refers to the 4% reduction in RH vs. the 15% reduction in RH compared to ambient. I believe a better description is 15 “percentage points” below ambient. For example, if the ambient RH is 90%, the PurpleAir monitor will read 75%. If the ambient RH is 50%, the PurpleAir monitor will read 35%. Of course, at very low ambient RH levels, the difference will be reduced by fewer than 15 percentage points.

1 Like
4

Lance, we’d love to see anything you can show us! Please provide this evidence, and we will be happy to re-evaluate our RH correction.

1 Like
5

HI Andrew–

Attached is a writeup on 2 years of observation of indoor Temperature and RH by two PurpleAir PA-II monitors, and six months of observation of outdoor T and RH by one PA-II monitor. I remembered the difference of about 15% (actually 16%) for the RH values (indoors) but forgot the rather larger mean RH difference of about 26% for the single outdoor monitor. I attribute the RH difference to the restricted RH range of about 30-70% indoors compared to 10-100% outdoors.

(Attachment PurpleAir Temperatures and RH compared to measured indoor and outdoor values.docx is missing)

2 Likes
6

Hi Adrian and all PurpleAir staff

I now know how Plantower calculates PM1 and PM2.5. I also know why they have zeros.

My paper (attached) supporting these claims was accepted today by Science of the Total Environment. In the next few days I expect I can provide a link to the published paper.

I claim that they calculate the number of particles in the smallest 3 size categories just as I do in the ALT-CF3 algorithm. However, instead of calculating PM2.5 by multiplying each size category by a different constant value determined by fitting to some calibration aerosol (which in their case they do not identify), they first add the particle numbers in the two smallest size categories (0.3-0.5 um and 0.5-1 um). They do this for both their PM1 and PM2.5 estimates in their CF1 algorithm… In addition, I believe they add a small constant value on the order of -1 ug/m3 to get their algorithm to go to zero when the true concentration is zero.

Using this model of their approach and testing it by results from four PurpleAir monitors collecting both indoor and outdoor data for 6 months, I can get nearly perfect estimates of their CF1 results.

image.png
image.png965×722 94 KB

Figure 5. The fit to the CF_1 algorithm for PM2.5 for sensor 1a using a fixed general model for all sensors: PM1 = 0.0042*(N1+N2) + 0.93*N3 -1.17.

Using this model which includes a value of -1.17 ug/m3 to be subtracted from every measurement, there were 18,000 negative results out of about 100,000 two-minute average measurements. All 18,000 cases were identified as zero in the CF1 results.

Comparing to the collocated ALT-CF3 estimates (using the recent estimate of 3.4 for the calibration factor), the CF1 algorithm overestimated PM2.5 by about 32%.

By the way, I would be delighted to be proved wrong, because the only way to do that would be for Plantower to tell us what their real algorithm is.

(Attachment Cracking the Code–final manuscript.docx is missing)

3 Likes
7

I’m attaching two tables from my Word document on temperature and RH differences between PurpleAir and ambient values.

Table 1. PurpleAir Temperature and RH compared to ambient values inside a home over 18 months.

N Mean SD SE Min 10th 25th Median 75th 90th Max
Matched Temperatures
Hobo Temp (oF) 407148 72.05 3.83 0.01 54.6 67.4 69.6 71.9 74.2 77.3 85.9
Mean PA Temp (oF) 407148 80.62 3.80 0.01 60.5 76 78 80.5 83 85.5 95
Matched RH
Hobo RH 2-min avg (%) 363746 46.88 4.76 0.01 23.5 40.3 43.7 47.4 50.3 52.5 63.3
Mean PA RH (%) 363746 30.66 3.33 0.01 17 26 28.5 31 33 34.5 39.5

PurpleAir temperatures averaged about 8.6 degrees (Fahrenheit) greater than ambient indoor temperatures, whereas the PurpleAir indoor RH values were about 16.2 percentage points below ambient indoor RH.

The greater range of T and RH outdoors will extend these relationships. Only about 6 months of outdoor data were collected from June to Dec 31, 2020. The temperature difference is about the same at 7.3 oF but the mean RH difference is much larger, at about 26.5% (Table 3).

Table 3. PurpleAir Temperature and RH compared to ambient values outside a home over 6 months.

N Mean SD SE Min 10th 25th Median 75th 90th Max
Hobo Outdoor Temp, °F 134879 60.9 14.5 0.04 32 43 51 58 71 82 112
Hobo Outdoor RH(%) 134879 70.0 22.7 0.06 12 37 51 75 91 96 100
PA Outdoor T 127533 68.2 13.9 0.04 40 51 59 65 78 89 115
PA Outdoor RH (%) 127533 43.5 15.2 0.04 5 22 31 46 57 62 72
2 Likes
8

The attached paper seems to be missing, or I’m missing it. Can you re-share?

9

I have now received the Author’s link to the new paper on “Cracking the Code” (discovering the “proprietary” CF_1 algorithm. This link should allow you to download the entire paper. It will be active for the next 50 days.

https://authors.elsevier.com/a/1hHvLB8ccyZrW

1 Like
10

I agree about the significant RH differences. I notice significant differences between the RH % reported by PA outdoors and my outdoor weather station (PA reports consistently lower RH%).

The weather station RH data closely matches other stations in the area and ties in with official data so I’m inclined to believe the PA RH measurements are too low.

Looking right now for example my weather station reports 70% RH and PA 51%.

11

I think an important thing to note about RH is that it is temperature-dependant (that is, relative to temperature). Warm air can hold more moisture than cold air, so as the air is heated by the PA’s electronics, the RH goes down.

Most humidity sensors derive RH by the absolute humidity adjusted to the temperature. If you artificially adjust the temperature reading down in the output, that won’t affect the RH reading because that is being calculated onboard the chip.

Generally speaking, the best way to calculate an accurate humidity is to use the dewpoint temperature, which reflects the absolute humidity. If your temperature reading is off, you might be able to calculate a plausible RH from the dewpoint and a corrected temperature value.

Getting accurate ambient temperature and humidity data out of internally located sensors on a device the size of a PA is a complex task. A lot depends on the humidity sensor calibration and temperature conversions onboard the chip. (The humidity sensor needs to know how hot it is to correctly report the sensor output). If we want to validate the PA as a device, the accuracy of the temp and RH sensors first needs to be evaluated by how well they are accurately reporting the temperature and RH conditions inside the PA enclosure, where they are located. Once this data is validated, then converting that data to obtain humidity readings in ambient air (outside the PA) might be possible with an external temperature input or a conversion factor.

For those of us who have built gaming computers, we are used to reading various temperature sensors inside the case and understanding what they mean - as the “ambient” sensor means the intake air inside the case, not necessarily the temperature in the room. To me, that is how I view the PA temperature and humidity data. It tells me more about the sensor itself than the outdoor air (especially if the sensor is getting direct or reflected solar irradiance, or is mounted to a heat-retaining material).