Loop API Calls for Historical Data

The historical API can be used to download PurpleAir data from any date range. However, there is a limit to the amount of data that can be collected per request. Multiple requests will need to be made to collect data past that limit.

The time limits for each average are listed below. Averages are on the left, and the time limit is on the right.

Average Time Limit
Real-time 2 days
10-minute 3 days
30-minute 7 days
1-hour 14 days
6-hour 90 days
1-day 1 year
1-week 5 years
1-month 20 years
1-year 100 years

Example

Say you were collecting real-time PM2.5 data from January 1 to January 4. Only 2 days of real-time data can be collected per request, so two requests need to be made; the first request for January 1-2 and the second request for January 3-4. These dates will be in UTC.

The request URLs may look like this:

Request 1
https://api.purpleair.com/v1/sensors/123456/history?start_timestamp=2023-01-01T00:00:00Z&end_timestamp=2023-01-03T00:00:00Z&fields=pm2.5_atm

Request 2
https://api.purpleair.com/v1/sensors/123456/history?start_timestamp=2023-01-03T00:00:00Z&end_timestamp=2023-01-05T00:00:00Z&fields=pm2.5_atm

Notice how the end timestamp for the first request is January 3. This is because this date is exclusive and will not appear in the data. The start timestamp is inclusive, meaning data on that date will be collected. The first example request will get data from January 1 at 12:00 a.m. to January 2 at 11:59 p.m.

Looping with Code

Programming languages will allow you to loop through a date range and automatically make the required number of API requests. The PurpleAir Data Download Tool does this in the background without the user needing programming experience.

1 Like