How to Make Efficient API Calls

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

Averaging Periods

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.

Modified Since

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.

Averaged Fields

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.

Group Calls

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.

Fields That Don’t Update Often

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

Unused or Rarely Used Fields

Field Name Description
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

Calculatable Data

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

Name Source Equation
scattering_coefficient Visibility Data Layers
deciviews Visibility Data Layers
visual_range Visibility Data Layers
3 Likes