API Fields Descriptions

Data API
1

This article is related to the PurpleAir API. If you are unfamiliar with it, check out our API Landing Page to get started.

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, Visibility Basics – Improve.
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).

12

Hey Lance,
Any chance I could get the link to this paper?

13

Noah–

Here it is.

(Attachment Cracking the code–STOTEN 893 2023.pdf is missing)

14

Noah–

I tried to send yoou the paper itself byt Purpleair does not allow it.

If you want the actual paper (it may be behind a paywall) you can send me your email address directly to lwallace73@gmail.com

Here are various papers onPurpleAir

  1. Wallace, L. (2024). Socioeconomic inequity of measured indoor and outdoor exposure to PM2.5: 5 Years of data from 14,000 low-cost particle monitors. Indoor Environments 1 (2024) 100016. https://doi.org/10.1016/j.indenv.2024.100016 .

  2. Wallace, L. (2023a). Cracking the code—Matching a proprietary algorithm for a low-cost sensor measuring PM1 and PM2.5. Science of the Total Environment 893.164874. https://www.researchgate.net/publication/373512209_Cracking_the_Code–final_manuscript

  3. Wallace, L. (2023b). Testing a New “Decrypted” Algorithm for Plantower Sensors Measuring PM2.5: Comparison with an Alternative Algorithm. Algorithms 2023, 16, 392. https://doi.org/10.3390/a16080392

  4. Wallace, L.; Zhao, T. (2023). Spatial Variation of PM2.5 Indoors and Outdoors: Results from 261 Regulatory Monitors Compared to 14,000 Low-Cost Monitors in Three Western States over 4.7 Years. Sensors 23, 4387. https://doi.org/10.3390/s23094387 .

  5. Wallace, L.A., Ott, W.R. (2023). Long-term indoor-outdoor PM2.5 measurements using
    PurpleAir sensors: an improved method of calculating indoor-generated and outdoor-infiltrated contributions to potential indoor exposure. Sensors 2023, 23(3), 1160. https://www.mdpi.com/1424-8220/23/3/1160 .

  6. Ott, W.R. L.A. Wallace, K.-C. Cheng, et al. (2022), Measuring PM2.5 concentrations from secondhand tobacco vs. marijuana smoke in 9 rooms of a detached 2-story house, Science of the Total Environment https://doi.org/10.1016/j.scitotenv.2022.158244

  7. Wallace, L.A., Zhao, T., Klepeis, N.R. (2022) Indoor contribution to PM2.5 exposure using all PurpleAir sites in Washington, Oregon, and California.Indoor Air 32: (9) 13105. https://onlinelibrary.wiley.com/doi/abs/10.1111/ina.13105.

  8. Wallace, L. Zhao, T. and Klepeis, N.E…(2022) Calibration of PurpleAir PA-I and PA-II monitors using daily mean PM2.5 concentrations measured in California, Washington, and Oregon from 2017 to 2021. Sensors 2022, 22, 4741. https://doi.org/10.3390/ s22134741 https://pubmed.ncbi.nlm.nih.gov/35808235/

  9. Wallace, L.(2022) Intercomparison of PurpleAir Sensor Performance over Three Years Indoors and Outdoors at a Home: Bias, Precision, and Limit of Detection Using an Improved Algorithm for Calculating PM2.5. Sensors 2022, 22, 2755. https://doi.org/10.3390/s22072755

  10. Cheng, K-C; Ott, W.R.; Wallace L.A.; Zhu. Y.; Hildemann, L. PM2.5 exposure close to marijuana smoking and vaping: A case study in residential indoor and outdoor settings. Science of The Total Environment, 802 (2022) 149897, ISSN 0048-9697, https://doi.org/10.1016/j.scitotenv.2021.149897 .

https://www.sciencedirect.com/science/article/pii/S004896972104972X

  1. Wallace, L., Bi, J., Ott, W.R., Sarnat, J.A. and Liu, Y. (2021) Calibration of low-cost PurpleAir outdoor monitors using an improved method of calculating PM2.5. Atmospheric Environment, 256 (2021) 118432. https//doi.org/10.1016/j.atmosenviron.2021.118432 https://www.sciencedirect.com/science/article/abs/pii/S135223102100251X

  2. Sun, L. and Wallace, L.A. (2021) Residential cooking and use of kitchen ventilation: The impact on exposure, Journal of the Air & Waste Management Association. https://www.tandfonline.com/doi/full/10.1080/10962247.2020.1823525

13. Wallace, L.A., Ott, W.R., Zhao, T., Cheng, K-C, and Hildemann, L.M. 2021 Method for estimating the volatility of aerosols using the Piezobalance: examples from vaping e-cigarette and marijuana liquids. Atmospheric Environment Volume 253, 15 May 2021, 118379. https://doi.org/10.1016/j.atmosenv.2021.118379

  1. Bi, J., Wallace, L., Sarnat, J.A. and Liu, Y. (2021). Characterizing outdoor infiltration and indoor contribution of PM2.5 with citizen-based low-cost monitoring data. *Environmental Pollution 276:*116793. https://pubmed.ncbi.nlm.nih.gov/33631689/

  2. Ott, W.R., Zhao, T., Cheng, K-C, Wallace, L.A., and Hildemann, L.M. (2021). Measuring indoor fine particle concentrations, emission rates, and decay rates from cannabis use in a residence. Atmospheric Environment. https://doi.org/10.1016/j.aeaoa.2021.100106

  3. Wallace, L., Ott, W., Zhao, T., Cheng, K-C, and Hildemann, L. (2020). Secondhand exposure from vaping marijuana: Concentrations, emissions, and exposures determined using both research-grade and low-cost monitors, Atmospheric Environment X, https://doi.org/10.1016/j.aeaoa.2020.100093 (Accessed 11/19/20)

  4. Zhao, T., Cheng, K-C, Ott, W.R., Wallace L.A., and Hildemann, L.M. (2020) Characteristics of secondhand cannabis smoke from common smoking methods: calibration factor, emission rate, and particle removal rate. Atmospheric Environment. https://doi.org/10.1016/j.atmosenv.2020.117731 (Accessed 11/19/20)

2 Likes
15

This is a huge help Thank you!

1 Like