API endpoint changing per PurpleAir

[gregrahn]

As of today, the endpoint http://www.purpleair.com/json is no longer in service.
https://community.purpleair.com/t/discontinuation-of-the-json-and-data-json-urls/713

PurpleAir is changing to a new API as mentioned here:
https://community.purpleair.com/t/purpleair-data-migration-to-bigquery-and-a-new-api/295

One can register for an API key by emailing PurpleAir Support [email protected]

The API for a sensor seems to have changed from
https://www.purpleair.com/json?show=61037
to
https://api.purpleair.com/v1/sensors/61037
where 61037 is the sensor id of interest.

The return payload has slightly changed as well.

Example return payload

{
  "api_version" : "V1.0.10-0.0.17",
  "time_stamp" : 1653680628,
  "data_time_stamp" : 1653680580,
  "sensor" : {
    "sensor_index" : 61037,
    "last_modified" : 1599001466,
    "date_created" : 1596752148,
    "last_seen" : 1631814936,
    "private" : 0,
    "is_owner" : 0,
    "name" : "Bay View",
    "icon" : 0,
    "location_type" : 0,
    "model" : "PA-II-SD",
    "hardware" : "2.0+OPENLOG+NO-DISK+DS3231+BME280+PMSX003-B+PMSX003-A",
    "led_brightness" : 15,
    "firmware_version" : "6.01",
    "firmware_upgrade" : "6.06a",
    "rssi" : -69,
    "uptime" : 8807,
    "pa_latency" : 252,
    "memory" : 15384,
    "position_rating" : 5,
    "latitude" : 37.42225,
    "longitude" : -122.066086,
    "altitude" : 13,
    "channel_state" : 3,
    "channel_flags" : 0,
    "channel_flags_manual" : 0,
    "channel_flags_auto" : 0,
    "confidence" : 100,
    "confidence_auto" : 100,
    "confidence_manual" : 100,
    "humidity" : 42,
    "humidity_a" : 42,
    "temperature" : 73,
    "temperature_a" : 73,
    "pressure" : 1011.8,
    "pressure_a" : 1011.79,
    "analog_input" : 0.01,
    "pm1.0" : 13.8,
    "pm1.0_a" : 11.9,
    "pm1.0_b" : 15.8,
    "pm1.0_atm" : 13.8,
    "pm1.0_cf_1" : 13.8,
    "pm2.5" : 20.9,
    "pm2.5_a" : 18.7,
    "pm2.5_b" : 23.0,
    "pm2.5_atm" : 20.9,
    "pm2.5_cf_1" : 20.9,
    "pm2.5_alt" : 12.8,
    "pm2.5_alt_a" : 11.8,
    "pm2.5_alt_b" : 13.8,
    "pm10.0" : 24.6,
    "pm10.0_a" : 22.6,
    "pm10.0_b" : 26.7,
    "pm10.0_atm" : 24.6,
    "pm10.0_cf_1" : 24.6,
    "scattering_coefficient" : 44.2,
    "scattering_coefficient_a" : 33.6,
    "scattering_coefficient_b" : 54.9,
    "deciviews" : 18.2,
    "deciviews_a" : 16.2,
    "deciviews_b" : 20.3,
    "visual_range" : 64.5,
    "visual_range_a" : 77.5,
    "visual_range_b" : 51.4,
    "0.3_um_count" : 2948,
    "0.3_um_count_a" : 2240,
    "0.3_um_count_b" : 3657,
    "0.5_um_count" : 773,
    "0.5_um_count_a" : 658,
    "0.5_um_count_b" : 888,
    "1.0_um_count" : 129,
    "1.0_um_count_a" : 132,
    "1.0_um_count_b" : 126,
    "2.5_um_count" : 12,
    "2.5_um_count_a" : 12,
    "2.5_um_count_b" : 13,
    "5.0_um_count" : 4,
    "5.0_um_count_a" : 4,
    "5.0_um_count_b" : 5,
    "10.0_um_count" : 3,
    "10.0_um_count_a" : 4,
    "10.0_um_count_b" : 3,
    "pm1.0_atm_a" : 11.86,
    "pm2.5_atm_a" : 18.72,
    "pm10.0_atm_a" : 22.61,
    "pm1.0_cf_1_a" : 11.86,
    "pm2.5_cf_1_a" : 18.72,
    "pm10.0_cf_1_a" : 22.61,
    "pm1.0_atm_b" : 15.83,
    "pm2.5_atm_b" : 23.0,
    "pm10.0_atm_b" : 26.68,
    "pm1.0_cf_1_b" : 15.83,
    "pm2.5_cf_1_b" : 23.0,
    "pm10.0_cf_1_b" : 26.68,
    "primary_id_a" : 1112993,
    "primary_key_a" : "HH3SFEB4DRCGKTCZ",
    "primary_id_b" : 1112995,
    "primary_key_b" : "GEOEZ7BCVPBN04IJ",
    "secondary_id_a" : 1112994,
    "secondary_key_a" : "NUST4ZTYPT4FVO3O",
    "secondary_id_b" : 1112996,
    "secondary_key_b" : "5J1ONTLW2LWIFE4S",
    "stats" : {"pm2.5" : 20.9, "pm2.5_10minute" : 21.4, "pm2.5_30minute" : 20.9, "pm2.5_60minute" : 20.6, "pm2.5_6hour" : 21.2, "pm2.5_24hour" : 18.7, "pm2.5_1week" : 20.6, "time_stamp" : 1631814936},
    "stats_a" : {"pm2.5" : 18.7, "pm2.5_10minute" : 20.1, "pm2.5_30minute" : 20.0, "pm2.5_60minute" : 19.9, "pm2.5_6hour" : 20.7, "pm2.5_24hour" : 18.4, "pm2.5_1week" : 20.3, "time_stamp" : 1631814936},
    "stats_b" : {"pm2.5" : 23.0, "pm2.5_10minute" : 22.6, "pm2.5_30minute" : 21.8, "pm2.5_60minute" : 21.4, "pm2.5_6hour" : 21.6, "pm2.5_24hour" : 19.0, "pm2.5_1week" : 20.9, "time_stamp" : 1631814936}
  }
}

[NathanBlais]

Unfortunate for us, this breaks the plugin entirely. It is a big issue.

[nashnix]

You can sidestep the issue entirely with HTTP Advanced Accessory. Your PurpleAir Sensor has on it a website which provides a JSON file; using HTTP Advanced Accessory, you can extract the raw values from your PurpleAir Sensor and expose them to HomeKit that way. It is unaffected by the API changeover, and the traffic is local within your home network (so you're never in danger of annoying PurpleAir with too many API requests).

I've shared the code I use to do it here, on another PurpleAir plugin that has also been deactivated by this problem. As I note in there though, this will give you two sensors that each provide a verbal air quality, a PM2.5, and a PM10 reading, not a single sensor; I haven't worked out any way to combine the A and B sensor outputs into a single averaged reading. My code bases the air quality reading off the PM2.5 reading.

[roycepope]

Thanks for sighting this issue. I was wondering why this plugin stopped working :(

[rxin]

I will spend some time reviewing the other patch and updating the plugin after Data and AI Summit later this month!

[roycepope]

@rxin Any update to addressing this issue? Thanks!

[jmkk]

Folks, here's a small update. I have just released a version 1.7.0 of this plugin which contains a workable solution similar to what @nashnix provided above, but more native - if you own your PurpleAir sensor, you can make this plugin talk directly to it over the local network instead of hitting internet API. Just configure the plugin's new localIPAddress option.

However, I will work on supporting the new public API, stay tuned.

[etomnash]

Thanks. That works nicely.

I always thought there should be an http/json server on board the PurpleAir, but never guessed the address as ipaddress/json. Thanks to nashnix for that!

[aacentric]

Have you been able to work out how to use the new public API yet? Our air quality here in NorCal is TERRIBLE and I miss having that info in HomeKit for my automatons. Thank you for your hard work!

[roycepope]

We forked this repo and someone added local access. It's working great now. Hate these fires though!

[aacentric]

Thanks @roycepope, but I'm trying to use the public API to pull from a web-based sensor, I don't actually own any myself. The 'HTTP Advanced Accessory' info above is a bit beyond my skill level unfortunately. I was able to get a public API 'read' and 'write' key from PurpleAir by e-mailing them, and can pull data from public sensors using curl 'GET' requests in terminal. Wondering if the plugin is able to support this yet.

[BrianAker]

For local access, I found that uninstalling the plugin and then reinstalling it fixed local access.
Thanks!

[jmkk]

Folks, please try out the new v2.0.0 which has support for the new purpleair.com API. Reach out to [email protected] to request your (read) API key, and configure it in the new version of the plugin. Open issue for any unexpected behavior, thank you!