openaq-mcp-server: get measurements
openaq_get_measurementsRead-onlyIdempotent
Historical measurement series for one pollutant at one station over a date range — for trend analysis and "was last week worse than the monthly average?". Pass a locationId and a parametersId and work in stations — you get the series for that pollutant at that station. Choose aggregation: raw (every reported value), hourly, or daily — daily and hourly add a per-bucket statistical summary (min, median, max, mean, sd). A date-only bound means the station's local calendar day. Large ranges produce thousands of rows and stage on a DataCanvas: the response returns a preview plus a canvasId and table name — call openaq_dataframe_describe on the canvasId for the table's columns, then openaq_dataframe_query to run SQL over it. Passing a canvas_id stages the series there whatever its size, so two stations land on one canvas for a side-by-side comparison. Values carry their unit; the server never converts between µg/m³, ppm, and ppb.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max rows per page from the API (1–1000). Default 1000. The tool pages internally up to the 5000-row pull ceiling. | |
| canvas_id | No | DataCanvas id from a prior openaq_get_measurements call, to put this series on the same canvas (e.g. to compare two stations' series side by side). Supplying it stages the series whatever its size. Reuse stages one table per sensor, so a second sensor adds a table while the same sensor overwrites its earlier series — the response says so when that happens. Omit to start fresh; the response returns a new canvas_id when the series overflows the inline preview. | |
| datetimeTo | No | End of the range, inclusive. A date "YYYY-MM-DD" covers that whole station-local day, closing at the next local midnight, so a DST day spans 23 or 25 hours; a full UTC "YYYY-MM-DDTHH:MM:SSZ" is sent as is. Must land after datetimeFrom — the two forms mix freely, so "2026-06-25" to "2026-06-25" is a valid one-day range. Omit for "up to now". effectiveRange echoes the instant sent. | |
| locationId | Yes | Station id from openaq_find_locations. | |
| aggregation | No | Time bucketing. "raw" = every reported value (often hourly at source). "hourly"/"daily" = server-side rollups with a statistical summary per bucket; an hour is labeled by the time it ends, and a day is the station's local calendar day. Use "daily" for multi-month trends to keep the series small; "raw" for fine-grained recent analysis. | raw |
| datetimeFrom | No | Start of the range, inclusive. A date "YYYY-MM-DD" opens at local midnight of that day in the station's timezone (UTC midnight when OpenAQ lists none); a full UTC "YYYY-MM-DDTHH:MM:SSZ" is sent as is. Omit to start from the sensor's earliest data — the series runs oldest first, so on a long-running station an open start fills the row cap with its oldest values; set datetimeFrom to reach recent ones. effectiveRange echoes the instant sent. | |
| parametersId | Yes | Parameter id to pull the series for (e.g. 2 = PM2.5 µg/m³). Get ids from openaq_list_parameters. Must be a parameter the station measures — find_locations lists each station's parameters. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| gaps | No | The first 20 missing intervals, oldest first. Omitted when gapCount is 0. | |
| error | No | Present when the call failed. Absent on success. | |
| notice | No | What limited this response or where the rest of it lives — the row cap, a failed page, a station with no timezone, an edge bucket clipped by the range, missing intervals, DataCanvas being unavailable, or the canvas table the series was staged on and the tools that read it. | |
| series | No | The (possibly previewed) series in the order OpenAQ returns it (oldest first). An hourly/daily series either skips a missing bucket or returns it with a null value — gapCount and gaps report both. Every row here is also rendered in the text output. When truncated, this is a preview of pulledCount rows — query canvasId for the rest. | |
| canvasId | No | DataCanvas id holding the staged series — pulledCount rows of it. Call openaq_dataframe_describe on this id for the table's columns, then openaq_dataframe_query to run SQL. Present whenever staging succeeded, which includes a series that fit inline on a canvas_id you supplied. | |
| gapCount | No | Missing intervals inside an hourly or daily series — a span between buckets that do not touch, or a bucket with a null value, merged where contiguous — counted over every pulled row, not only the preview. 0 when nothing is missing; absent for raw, whose rows follow no fixed cadence. | |
| location | No | Station the series came from | |
| rowCount | No | Rows in this response (preview length when spilled) | |
| sensorId | No | Resolved sensor id the series was pulled from | |
| parameter | No | What was measured, resolved from the station's sensor | |
| tableName | No | Canvas table holding the staged series (e.g. "measurements_1701"). openaq_dataframe_describe lists its columns; reference this name in openaq_dataframe_query SQL. One table per sensor, so re-staging the same sensor on this canvas overwrites it. | |
| truncated | No | True when the series exceeded the inline limit, so series is a preview of the pulled rows. Absent/false when every pulled row is inline. It describes the preview only — canvasId reports whether the rows were staged, and pullComplete whether the pull itself finished. | |
| totalCount | No | Rows in the full series for this range. A floor rather than an exact count when totalCountIsLowerBound is set; never below pulledCount. | |
| aggregation | No | Bucketing applied | |
| pulledCount | No | Rows pulled from OpenAQ, at most 5000 — the canvas table's row count when canvasId is present. Equals rowCount when the whole series fit inline; larger when series is a preview. | |
| pullComplete | No | True when pulledCount is the whole series for the requested range. False when the 5000-row cap or a failed page stopped the pull early — the rows past that point are in neither this response nor the canvas table, and the notice says how to reach them. | |
| effectiveRange | No | The range sent to OpenAQ as UTC instants — date-only bounds expanded to the station's local day. | |
| totalCountIsLowerBound | No | Set when totalCount is only a floor: the pull stopped early and OpenAQ reported the range total as ">N" instead of an exact number, so more rows exist than totalCount states. Absent when the count is exact. |