This article outlines many ways that you can reduce the points usage of your API calls. These can involve either lowering the base cost of the call, or avoiding querying unnecessary fields.
Some of these tips or fields listed are only applicable to certain API endpoints
The easiest way you can reduce your point cost is by using larger averaging periods. For example, changing a request from real-time to hourly results in 30 times less data points, and a similar change in cost.
When querying real-time data from Get Sensors Data or Get Members Data, the “modified_since” parameter can be used to only return data from sensors that have reported since a given timestamp. This can easily be used with the timestamp for your last call to only receive newly reported data.
For example, if we send a request to Get Sensors Data, the response should include an element of metadata called “time_stamp.” If we set the modified_since parameter to the time_stamp of our last API call, then we will only receive data for sensors that have reported new data since the previous API call.
The “modified_since” parameter is based on when a sensor has last reported data, while the “last_modified” field contains information on when a sensors’s registration was last changed. Though similarly named, they operate differently.
Many fields, such as pm2.5_atm or temperature, have an averaged form of the field as well as a and b channels available. For historical data fields where a and b channels are available, we always recommend querying the a and b channels separately, and averaging the data locally.
This is because averaged fields cost 2 points per row, while individual channel data is 1 point per row. If a sensor has only reported “temperature_a”, but no data for “temperature_b”, then requesting the averaged field “temperature,” will still deduct 2 points per row of data returned. However, requesting temperature_a and temperature_b separately will only deduct 1 point for temperature_a per row of data returned. Since there is no data for temperature_b, you will not be deducted any points for that field in the returned data.
While many PurpleAir sensors report two channels of PM data, only a few can report two channels of temperature, humidity, and pressure data. Currently, no PurpleAir sensors can report two channels of VOC data.
If you are querying real-time data for many sensors at once, the group endpoints allow you to query data from many sensors at once. This requires that you first create a group and add members to a group. You can then obtain real-time data for all group members with a single request using the Get Members Data endpoint.
This means that instead of the base cost being 1 point for every sensor you query, the base cost will instead only be 5 points for data from the entire group.
The following fields don’t change often, and typically don’t require frequent API calls.
The field last_modified indicates when the registration for a sensor was last updated. You can keep track of this field for a sensor index, and only request registration related information if the registration has been updated.
|Field Name||When It Changes|
|date_created||This field will never change for a sensor index|
|position_rating||The position rating only changes when a device is connected to a new WiFi network or has its registration modified.|
|hardware||The hardware detected by the sensor doesn’t change frequently, and typically only changes when a component fails|
|firmware_version||This will change when a device is updated to a newer firmware version. Devices will automatically update when newer firmware becomes available|
|last_modified||This indicates when the registration was last modified|
|name||This can be changed during registration|
|location_type||This can be changed during registration|
|private||This can be changed during registration|
|latitude||This can be changed during registration|
|longitude||This can be changed during registration|
|altitude||This can be changed during registration|
|led_brightness||This can be changed during registration|
|ozone1||An extremely limited number of PurpleAir sensors have ever reported ozone data. At the time of writing, only five sensors can be seen on the map with the “Ozone (ppb)” data layer selected|
|icon||This is a flag reserved for future use to reference an icon for the sensor|
|pa_latency||This field measures the time taken to send data to the PurpleAir server in milliseconds|
|memory||This value is primarily used by PurpleAir for diagnostic information of sensors|
|analog_input||This is the analog voltage on the ADC input of the PurpleAir sensor control board|
|confidence_manual||We recommend using the confidence field instead, as it takes confidence_manual into account|
|confidence_auto||We recommend using the confidence field instead, as it takes confidence_auto into account|
|primary_id_a||A legacy field from when PurpleAir used ThingSpeak|
|primary_key_a||A legacy field from when PurpleAir used ThingSpeak|
|secondary_id_a||A legacy field from when PurpleAir used ThingSpeak|
|secondary_key_a||A legacy field from when PurpleAir used ThingSpeak|
|primary_id_b||A legacy field from when PurpleAir used ThingSpeak|
|primary_key_b||A legacy field from when PurpleAir used ThingSpeak|
|secondary_id_b||A legacy field from when PurpleAir used ThingSpeak|
|secondary_key_b||A legacy field from when PurpleAir used ThingSpeak|
The following fields can be derived from other sensor data using formulas available on the PurpleAir community forums. They are still available on the API, but API users concerned about cost can also locally calculate these values