Server definition
- Hash
- sha256:0a5bfcd96b3b6af0306dbb370691d20beba3555439d8346e0e021f89c21737d0
- What it is
- What a remote MCP server returned when asked what it offers: 7 tools
The blob, as servednamed by its sha256
{
"instructions": "Measured air quality from physical sensors (OpenAQ v3) — the ground-truth counterpart to modeled air-quality grids. Workflow: openaq_find_locations (find stations near a point / in a bbox / by country) → openaq_get_readings (latest values) or openaq_get_measurements (historical series). An empty find_locations result means NO monitoring coverage, NOT clean air — widen the search area, check openaq_list_countries, or fall back to open-meteo-mcp-server for modeled coverage. Units vary by sensor and are NEVER converted; the same pollutant has multiple parameter ids for different units (use openaq_list_parameters to disambiguate). Large measurement series stage on a DataCanvas (requires CANVAS_PROVIDER_TYPE=duckdb) — call openaq_dataframe_describe on the returned canvasId for the table columns, then openaq_dataframe_query to run SQL.",
"tools": [
{
"description": "List the tables and columns staged on a DataCanvas so you can write valid SQL for openaq_dataframe_query without guessing column names. Returns each measurement table (measurements_<sensorId>) with its row count and column names. Requires DataCanvas to be enabled.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"canvas_id": {
"description": "DataCanvas id returned by openaq_get_measurements — minted when a series overflowed the inline preview, or the canvas_id you passed it.",
"pattern": "^[A-Za-z0-9_-]{10}$",
"type": "string"
}
},
"required": [
"canvas_id"
],
"type": "object"
},
"name": "openaq_dataframe_describe",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"tables"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode. Declared by this tool: `canvas_unavailable`: DataCanvas is not enabled (CANVAS_PROVIDER_TYPE is not duckdb). `canvas_not_found`: The canvas_id is unknown or its canvas has expired. Other values are possible when a failure originates below the handler.",
"examples": [
"canvas_unavailable",
"canvas_not_found"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"notice": {
"description": "Guidance when the canvas holds no tables yet.",
"type": "string"
},
"tables": {
"description": "Tables currently staged on the canvas.",
"items": {
"additionalProperties": false,
"description": "A staged measurement table with its columns",
"properties": {
"columns": {
"description": "Column names available for SELECT.",
"items": {
"type": "string"
},
"type": "array"
},
"name": {
"description": "Table name — reference it in openaq_dataframe_query SQL.",
"type": "string"
},
"rowCount": {
"description": "Rows staged in this table.",
"type": "number"
}
},
"required": [
"name",
"rowCount",
"columns"
],
"type": "object"
},
"type": "array"
}
},
"type": "object"
}
},
{
"description": "Run a read-only SQL SELECT against the measurement tables openaq_get_measurements staged on a DataCanvas. Reference tables by the name the measurements call returned (measurements_<sensorId>). For aggregation (monthly means, exceedance counts) and cross-sensor comparison over series too large to inline. Only SELECT is allowed — writes, DDL, and file/network table functions are rejected. Responses carry at most 200 rows; aggregate in SQL, or page with ORDER BY plus LIMIT/OFFSET, rather than selecting a whole table.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"canvas_id": {
"description": "DataCanvas id returned by openaq_get_measurements — minted when a series overflowed the inline preview, or the canvas_id you passed it.",
"pattern": "^[A-Za-z0-9_-]{10}$",
"type": "string"
},
"sql": {
"description": "Read-only SELECT. Reference tables by the names openaq_get_measurements returned (e.g. measurements_1701). Use openaq_dataframe_describe first to see table and column names.",
"type": "string"
}
},
"required": [
"canvas_id",
"sql"
],
"type": "object"
},
"name": "openaq_dataframe_query",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"rows",
"rowCount"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode. Declared by this tool: `canvas_unavailable`: DataCanvas is not enabled (CANVAS_PROVIDER_TYPE is not duckdb). `canvas_not_found`: The canvas_id is unknown or its canvas has expired. `missing_table`: The SQL references a table that is not staged on this canvas (dropped, expired, or misspelled). Other values are possible when a failure originates below the handler.",
"examples": [
"canvas_unavailable",
"canvas_not_found",
"missing_table"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"notice": {
"description": "How to reach the rest of the result when the row cap cut it short.",
"type": "string"
},
"rowCount": {
"description": "Rows returned in this response, always equal to rows.length. It is the cap (200) when truncated is set, not the size of the full result.",
"type": "number"
},
"rows": {
"description": "Result rows, at most 200. Every row here is also rendered in the text output — the two surfaces carry the same set.",
"items": {
"additionalProperties": {},
"propertyNames": {
"type": "string"
},
"type": "object"
},
"type": "array"
},
"truncated": {
"description": "True when the query matched more than 200 rows and the response was cut to the cap. Absent when the whole result fit. Page through the rest with ORDER BY plus LIMIT/OFFSET in your own SQL.",
"type": "boolean"
}
},
"type": "object"
}
},
{
"description": "Find air-quality monitoring stations (measured by physical sensors, not modeled) near a point, within a bounding box, or by country, optionally narrowed to one parameter, one station class (reference monitors or low-cost sensors, mobile or fixed), or one provider network. Returns each station's id, name, coordinates, distance from the query point (when searching by coordinates), country, provider name and id, the parameters its sensors measure, and the timestamp of its most recent data (datetimeLast). Required first step: openaq_get_readings and openaq_get_measurements key on the location id this returns. Coverage is uneven and real — a station only reports the parameters it measures, and the absence of a nearby station means no monitoring there, not clean air. For dense modeled coverage anywhere on Earth, use open-meteo-mcp-server's air-quality tool instead.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"bbox": {
"description": "Bounding box as \"minLon,minLat,maxLon,maxLat\" (west,south,east,north), with minLon ≤ maxLon and minLat ≤ maxLat. Alternative to coordinates+radius for area sweeps. Results have no distance field (no center point).",
"pattern": "^(-?\\d+(\\.\\d+)?,){3}-?\\d+(\\.\\d+)?$",
"type": "string"
},
"coordinates": {
"description": "Center point as \"latitude,longitude\" (e.g. \"47.6062,-122.3321\"). Pair with radius for a near-me search. Resolve a place name to coordinates with openstreetmap-mcp-server or open-meteo geocode first. Provide either coordinates+radius OR bbox, not both.",
"pattern": "^-?\\d{1,3}(\\.\\d+)?,-?\\d{1,3}(\\.\\d+)?$",
"type": "string"
},
"iso": {
"description": "Restrict to a country by OpenAQ country code: ISO 3166-1 alpha-2 (e.g. \"US\", \"IN\", \"DE\"; either case), or \"-99\" where OpenAQ lists a country with no ISO code. Take codes from openaq_list_countries. Combine with bbox/coordinates to scope, or use alone for a country-wide list.",
"pattern": "^(?:[A-Za-z]{2}|-99)$",
"type": "string"
},
"limit": {
"default": 20,
"description": "Max stations to return (1–100). Default 20. Results are ordered by distance when searching by coordinates.",
"maximum": 100,
"minimum": 1,
"type": "integer"
},
"mobile": {
"description": "Mobility filter: true returns only mobile stations, false only fixed ones. Omit for both.",
"type": "boolean"
},
"monitor": {
"description": "Station class filter: true returns only reference-grade monitors, false only low-cost sensors. Omit for both.",
"type": "boolean"
},
"page": {
"default": 1,
"description": "Which page of results to return (1-based). Default 1. The only way past the 100-station cap: with limit 100, page 2 returns stations 101–200. Distance ordering applies within a page, not across pages, so paging is for iso/bbox sweeps — a near-me coordinates search should stay on page 1. A page past the last one fails with page_exhausted.",
"maximum": 9007199254740991,
"minimum": 1,
"type": "integer"
},
"parametersId": {
"description": "Only return stations that measure this parameter id (e.g. 2 = PM2.5 µg/m³). Get ids from openaq_list_parameters — the same pollutant has several ids for different units. Narrows the station set; each returned station still lists all its sensors.",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"type": "integer"
},
"providersId": {
"description": "Only return stations from this OpenAQ provider (data network) id — read it from a previous result's providerId (e.g. 119 = AirNow).",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"type": "integer"
},
"radius": {
"description": "Search radius in metres around coordinates (1–25000; the API hard-caps at 25000). Default 12000 (~12km). Requires coordinates — a radius sent with only bbox or iso is rejected.",
"maximum": 25000,
"minimum": 1,
"type": "integer"
}
},
"type": "object"
},
"name": "openaq_find_locations",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"locations",
"totalCount"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"cap": {
"description": "The limit that was applied.",
"type": "number"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode. Declared by this tool: `no_locations_found`: No monitoring stations match the given area or filters. `page_exhausted`: A page past the first returned no stations — the results end before it. `no_search_scope`: None of coordinates, bbox, or iso was provided. `invalid_search_scope`: coordinates and bbox were both provided, or radius was provided without coordinates. `upstream_error`: OpenAQ returned 5xx or an unreadable body on every retry. `rate_limited`: OpenAQ returned 429 — the request budget for this key is exhausted. `upstream_timeout`: OpenAQ did not respond within the request timeout on every retry. `invalid_api_key`: OpenAQ returned 401 — the configured OPENAQ_API_KEY is missing, invalid, or revoked. Other values are possible when a failure originates below the handler.",
"examples": [
"no_locations_found",
"page_exhausted",
"no_search_scope",
"invalid_search_scope",
"upstream_error",
"rate_limited",
"upstream_timeout",
"invalid_api_key"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"locations": {
"description": "Matching stations on this page, never empty: a query with no match fails with no_locations_found (no monitoring coverage, NOT clean air), and a page past the last with page_exhausted.",
"items": {
"additionalProperties": false,
"description": "A matching monitoring station with its sensors and data span",
"properties": {
"coordinates": {
"anyOf": [
{
"additionalProperties": false,
"properties": {
"latitude": {
"description": "Station latitude (decimal degrees)",
"type": "number"
},
"longitude": {
"description": "Station longitude (decimal degrees)",
"type": "number"
}
},
"required": [
"latitude",
"longitude"
],
"type": "object"
},
{
"type": "null"
}
],
"description": "Station location. Null when OpenAQ lists no latitude or no longitude."
},
"country": {
"anyOf": [
{
"additionalProperties": false,
"properties": {
"code": {
"description": "OpenAQ country code: ISO 3166-1 alpha-2, or \"-99\" where OpenAQ lists none",
"type": "string"
},
"name": {
"description": "Country name",
"type": "string"
}
},
"required": [
"code",
"name"
],
"type": "object"
},
{
"type": "null"
}
],
"description": "Country the station is in. Null when OpenAQ lists none."
},
"datetimeFirst": {
"anyOf": [
{
"additionalProperties": false,
"properties": {
"local": {
"description": "Timestamp in the station's local timezone",
"type": "string"
},
"utc": {
"description": "Timestamp in UTC (ISO 8601)",
"type": "string"
}
},
"required": [
"utc",
"local"
],
"type": "object"
},
{
"type": "null"
}
],
"description": "Timestamp of the station's first available measurement."
},
"datetimeLast": {
"anyOf": [
{
"additionalProperties": false,
"properties": {
"local": {
"description": "Timestamp in the station's local timezone",
"type": "string"
},
"utc": {
"description": "Timestamp in UTC (ISO 8601)",
"type": "string"
}
},
"required": [
"utc",
"local"
],
"type": "object"
},
{
"type": "null"
}
],
"description": "Timestamp of the station's most recent measurement. Tells you whether \"latest\" will be minutes or hours/days old. Null if the station has never reported."
},
"distanceMeters": {
"description": "Distance from the query coordinates in metres. Null when searching by bbox or iso (no center point).",
"type": [
"number",
"null"
]
},
"id": {
"description": "Location id — pass to openaq_get_readings / openaq_get_measurements",
"type": "number"
},
"isMobile": {
"description": "True if the station is mobile (coordinates may vary over time)",
"type": "boolean"
},
"isMonitor": {
"description": "True for reference-grade government monitors; false for low-cost sensors. Reference monitors are more reliable for regulatory comparison.",
"type": "boolean"
},
"locality": {
"description": "Locality or metro area, when provided",
"type": [
"string",
"null"
]
},
"name": {
"description": "Station name",
"type": "string"
},
"parameters": {
"description": "Parameters this station measures, each with its sensor unit. The station has one sensor per parameter.",
"items": {
"additionalProperties": false,
"description": "A parameter the station measures, with its sensor unit",
"properties": {
"displayName": {
"description": "Human-readable pollutant name",
"type": [
"string",
"null"
]
},
"id": {
"description": "Parameter id — use as parametersId in get_readings / get_measurements",
"type": "number"
},
"name": {
"description": "Pollutant code (e.g. \"pm25\", \"o3\")",
"type": "string"
},
"unit": {
"description": "Measurement unit for this sensor (e.g. \"µg/m³\", \"ppm\"). Units vary by sensor — never assume.",
"type": "string"
}
},
"required": [
"id",
"name",
"unit",
"displayName"
],
"type": "object"
},
"type": "array"
},
"provider": {
"description": "Data provider / network (e.g. \"AirNow\", \"OpenAQ LCS\"). Null when OpenAQ lists none.",
"type": [
"string",
"null"
]
},
"providerId": {
"description": "OpenAQ provider id — pass as providersId to restrict a search to this network. Null when OpenAQ lists no provider.",
"type": [
"number",
"null"
]
}
},
"required": [
"id",
"name",
"locality",
"country",
"coordinates",
"distanceMeters",
"provider",
"providerId",
"isMonitor",
"isMobile",
"parameters",
"datetimeLast",
"datetimeFirst"
],
"type": "object"
},
"type": "array"
},
"notice": {
"description": "Guidance on a full page: the next page to request, or how to narrow the search.",
"type": "string"
},
"shown": {
"description": "Number of stations returned.",
"type": "number"
},
"totalCount": {
"description": "Stations counted through this page: (page − 1) × limit plus the stations returned. Exact on a page that came back short of the limit (the last page); a floor when totalCountIsLowerBound is true.",
"type": "number"
},
"totalCountIsLowerBound": {
"description": "True when this page came back full: at least totalCount stations match, and the next page may hold more.",
"type": "boolean"
},
"truncated": {
"description": "True when this page came back full (the limit was reached), so the next page may hold more stations.",
"type": "boolean"
}
},
"type": "object"
}
},
{
"description": "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.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"aggregation": {
"default": "raw",
"description": "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.",
"enum": [
"raw",
"hourly",
"daily"
],
"type": "string"
},
"canvas_id": {
"description": "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.",
"pattern": "^[A-Za-z0-9_-]{10}$",
"type": "string"
},
"datetimeFrom": {
"description": "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.",
"pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}Z)?$",
"type": "string"
},
"datetimeTo": {
"description": "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.",
"pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}Z)?$",
"type": "string"
},
"limit": {
"default": 1000,
"description": "Max rows per page from the API (1–1000). Default 1000. The tool pages internally up to the 5000-row pull ceiling.",
"maximum": 1000,
"minimum": 1,
"type": "integer"
},
"locationId": {
"description": "Station id from openaq_find_locations.",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"type": "integer"
},
"parametersId": {
"description": "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.",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"type": "integer"
}
},
"required": [
"locationId",
"parametersId"
],
"type": "object"
},
"name": "openaq_get_measurements",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"location",
"parameter",
"sensorId",
"aggregation",
"series",
"rowCount",
"pulledCount",
"pullComplete",
"totalCount",
"effectiveRange"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"aggregation": {
"description": "Bucketing applied",
"enum": [
"raw",
"hourly",
"daily"
],
"type": "string"
},
"canvasId": {
"description": "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.",
"type": "string"
},
"effectiveRange": {
"additionalProperties": false,
"description": "The range sent to OpenAQ as UTC instants — date-only bounds expanded to the station's local day.",
"properties": {
"datetimeFrom": {
"description": "Lower bound sent to OpenAQ, UTC. Null when datetimeFrom was omitted.",
"type": [
"string",
"null"
]
},
"datetimeTo": {
"description": "Upper bound sent to OpenAQ, UTC. Null when datetimeTo was omitted.",
"type": [
"string",
"null"
]
}
},
"required": [
"datetimeFrom",
"datetimeTo"
],
"type": "object"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode. Declared by this tool: `location_not_found`: The locationId does not exist. `parameter_not_at_location`: No sensor at the station measures parametersId (often the wrong unit variant was chosen). `no_data_for_range`: The sensor has no measurements in the requested date range. `invalid_date_range`: The range is empty — once date-only bounds are expanded to the station's local day, datetimeTo does not land after datetimeFrom. `canvas_not_found`: The supplied canvas_id is unknown or has expired, so the series cannot be staged onto it. `upstream_error`: OpenAQ returned 5xx or an unreadable body on every retry. `rate_limited`: OpenAQ returned 429 — the request budget for this key is exhausted. `upstream_timeout`: OpenAQ did not respond within the request timeout on every retry. `invalid_api_key`: OpenAQ returned 401 — the configured OPENAQ_API_KEY is missing, invalid, or revoked. Other values are possible when a failure originates below the handler.",
"examples": [
"location_not_found",
"parameter_not_at_location",
"no_data_for_range",
"invalid_date_range",
"canvas_not_found",
"upstream_error",
"rate_limited",
"upstream_timeout",
"invalid_api_key"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"gapCount": {
"description": "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.",
"type": "number"
},
"gaps": {
"description": "The first 20 missing intervals, oldest first. Omitted when gapCount is 0.",
"items": {
"additionalProperties": false,
"description": "One missing interval",
"properties": {
"datetimeFrom": {
"description": "Start of the missing interval, UTC",
"type": "string"
},
"datetimeTo": {
"description": "End of the missing interval, UTC",
"type": "string"
}
},
"required": [
"datetimeFrom",
"datetimeTo"
],
"type": "object"
},
"type": "array"
},
"location": {
"additionalProperties": false,
"description": "Station the series came from",
"properties": {
"id": {
"description": "Station id",
"type": "number"
},
"name": {
"description": "Station name",
"type": "string"
},
"provider": {
"description": "Network that operates the station — cite it alongside OpenAQ. Null when OpenAQ lists none.",
"type": [
"string",
"null"
]
},
"providerId": {
"description": "Provider id, usable as providersId in openaq_find_locations. Null when OpenAQ lists none.",
"type": [
"number",
"null"
]
},
"timezone": {
"description": "IANA timezone of the station (e.g. \"America/Los_Angeles\"). Daily buckets and date-only bounds follow its calendar days. Null when OpenAQ lists none.",
"type": [
"string",
"null"
]
}
},
"required": [
"id",
"name",
"provider",
"providerId",
"timezone"
],
"type": "object"
},
"notice": {
"description": "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.",
"type": "string"
},
"parameter": {
"additionalProperties": false,
"description": "What was measured, resolved from the station's sensor",
"properties": {
"displayName": {
"description": "Human-readable pollutant name",
"type": [
"string",
"null"
]
},
"id": {
"description": "Parameter id",
"type": "number"
},
"name": {
"description": "Pollutant code",
"type": "string"
},
"unit": {
"description": "Unit for every value in this series. The server does not convert units.",
"type": "string"
}
},
"required": [
"id",
"name",
"unit",
"displayName"
],
"type": "object"
},
"pullComplete": {
"description": "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.",
"type": "boolean"
},
"pulledCount": {
"description": "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.",
"type": "number"
},
"rowCount": {
"description": "Rows in this response (preview length when spilled)",
"type": "number"
},
"sensorId": {
"description": "Resolved sensor id the series was pulled from",
"type": "number"
},
"series": {
"description": "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.",
"items": {
"additionalProperties": false,
"description": "One bucket in the series, with its value and (for rollups) statistics",
"properties": {
"datetimeFrom": {
"description": "Bucket start, UTC (ISO 8601)",
"type": "string"
},
"datetimeTo": {
"description": "Bucket end, UTC (ISO 8601)",
"type": "string"
},
"flagged": {
"description": "True if the source flagged this value (quality concern)",
"type": "boolean"
},
"percentComplete": {
"description": "Coverage of the bucket as OpenAQ reports it — observed readings as a percentage of expected ones. Low values flag gappy data. Usually 0–100, but it exceeds 100 when a bucket holds more readings than expected, e.g. 200 on the hour a DST fall-back repeats",
"type": [
"number",
"null"
]
},
"summary": {
"anyOf": [
{
"additionalProperties": false,
"properties": {
"avg": {
"description": "Mean reading in the bucket",
"type": [
"number",
"null"
]
},
"max": {
"description": "Maximum reading in the bucket",
"type": [
"number",
"null"
]
},
"median": {
"description": "Median reading in the bucket",
"type": [
"number",
"null"
]
},
"min": {
"description": "Minimum reading in the bucket",
"type": [
"number",
"null"
]
},
"sd": {
"description": "Standard deviation — null when only one reading in the bucket",
"type": [
"number",
"null"
]
}
},
"required": [
"min",
"median",
"max",
"avg",
"sd"
],
"type": "object"
},
{
"type": "null"
}
],
"description": "Per-bucket statistics — present for hourly/daily, null for raw. Every field is null in a gap bucket"
},
"value": {
"description": "Value for the bucket (the measurement for raw; the bucket aggregate for hourly/daily). Null for a gap bucket the sensor reported nothing into — the bucket is kept so the series stays evenly spaced on the time axis",
"type": [
"number",
"null"
]
}
},
"required": [
"datetimeFrom",
"datetimeTo",
"value",
"summary",
"percentComplete",
"flagged"
],
"type": "object"
},
"type": "array"
},
"tableName": {
"description": "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.",
"type": "string"
},
"totalCount": {
"description": "Rows in the full series for this range. A floor rather than an exact count when totalCountIsLowerBound is set; never below pulledCount.",
"type": "number"
},
"totalCountIsLowerBound": {
"description": "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.",
"type": "boolean"
},
"truncated": {
"description": "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.",
"type": "boolean"
}
},
"type": "object"
}
},
{
"description": "Latest measured value for every sensor at a monitoring station — the current-conditions tool. Returns one record per parameter, each with the value, its unit, the UTC and local timestamp, and the sensor id, joined so every value carries its pollutant and unit (the raw latest feed is keyed only by sensor id). The station block names its provider (for attribution) and timezone. Pass a locationId from openaq_find_locations, or pass coordinates to auto-resolve to the nearest station that measures the requested parametersId. Data recency varies by station reporting cadence — read each value's timestamp to know whether \"latest\" is minutes or hours old. These are measured observations with coverage gaps, not a modeled grid.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"coordinates": {
"description": "Fallback \"latitude,longitude\" when you do not have a locationId — resolves to the nearest station (within 25km) that measures parametersId, then reads its latest values. Requires parametersId.",
"pattern": "^-?\\d{1,3}(\\.\\d+)?,-?\\d{1,3}(\\.\\d+)?$",
"type": "string"
},
"locationId": {
"description": "Station id from openaq_find_locations. Provide this OR coordinates. When set, returns the latest value for every sensor at this station.",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"type": "integer"
},
"parametersId": {
"description": "Required with coordinates: which parameter id the nearest station must measure (get ids from openaq_list_parameters). With locationId, optionally filters the returned values to this parameter id; omit to get all sensors.",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"type": "integer"
}
},
"type": "object"
},
"name": "openaq_get_readings",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"location",
"readings"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode. Declared by this tool: `location_not_found`: The locationId does not exist (API returns {\"detail\":\"Location not found\"}). `parameter_not_at_location`: No sensor at the resolved station measures parametersId (often the wrong unit variant was chosen). `no_station_near_coordinates`: The 25km auto-resolution sweep found no station measuring the requested parametersId. `no_recent_values`: The station has the requested sensors but its latest feed carried no values for them. `invalid_location_scope`: Both locationId and coordinates were provided, or neither was. `missing_coordinates_parameter`: coordinates was provided without parametersId. `upstream_error`: OpenAQ returned 5xx or an unreadable body on every retry. `rate_limited`: OpenAQ returned 429 — the request budget for this key is exhausted. `upstream_timeout`: OpenAQ did not respond within the request timeout on every retry. `invalid_api_key`: OpenAQ returned 401 — the configured OPENAQ_API_KEY is missing, invalid, or revoked. Other values are possible when a failure originates below the handler.",
"examples": [
"location_not_found",
"parameter_not_at_location",
"no_station_near_coordinates",
"no_recent_values",
"invalid_location_scope",
"missing_coordinates_parameter",
"upstream_error",
"rate_limited",
"upstream_timeout",
"invalid_api_key"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"location": {
"additionalProperties": false,
"description": "The station these readings came from",
"properties": {
"coordinates": {
"anyOf": [
{
"additionalProperties": false,
"properties": {
"latitude": {
"description": "Station latitude (decimal degrees)",
"type": "number"
},
"longitude": {
"description": "Station longitude (decimal degrees)",
"type": "number"
}
},
"required": [
"latitude",
"longitude"
],
"type": "object"
},
{
"type": "null"
}
],
"description": "Station coordinates. Null when OpenAQ lists no latitude or no longitude."
},
"datetimeLast": {
"anyOf": [
{
"additionalProperties": false,
"properties": {
"local": {
"description": "Timestamp in the station's local timezone",
"type": "string"
},
"utc": {
"description": "Timestamp in UTC (ISO 8601)",
"type": "string"
}
},
"required": [
"utc",
"local"
],
"type": "object"
},
{
"type": "null"
}
],
"description": "Timestamp of the station's most recent measurement — tells you whether \"latest\" is minutes or hours old before reading per-value timestamps. Null if the station has never reported."
},
"distanceMeters": {
"description": "Distance from query coordinates in metres, when resolved via coordinates; null when called by locationId",
"type": [
"number",
"null"
]
},
"id": {
"description": "Station id",
"type": "number"
},
"name": {
"description": "Station name",
"type": "string"
},
"provider": {
"description": "Network that operates the station (e.g. \"AirNow\") — cite it alongside OpenAQ. Null when OpenAQ lists none.",
"type": [
"string",
"null"
]
},
"providerId": {
"description": "Provider id, usable as providersId in openaq_find_locations. Null when OpenAQ lists none.",
"type": [
"number",
"null"
]
},
"timezone": {
"description": "IANA timezone of the station",
"type": [
"string",
"null"
]
}
},
"required": [
"id",
"name",
"coordinates",
"provider",
"providerId",
"timezone",
"distanceMeters",
"datetimeLast"
],
"type": "object"
},
"notice": {
"description": "Set when coordinate resolution compared a full 1,000-station page: more stations may match, so the station returned is the nearest of the first 1,000 OpenAQ lists, not necessarily the nearest overall.",
"type": "string"
},
"readings": {
"description": "Latest value per sensor. An old datetime means the station reports infrequently or is stale — not that the value is current.",
"items": {
"additionalProperties": false,
"description": "Latest value for one sensor, with its pollutant and unit",
"properties": {
"datetimeLocal": {
"description": "Measurement time in the station's local timezone",
"type": "string"
},
"datetimeUtc": {
"description": "Measurement time, UTC (ISO 8601)",
"type": "string"
},
"parameter": {
"additionalProperties": false,
"description": "What was measured",
"properties": {
"displayName": {
"description": "Human-readable pollutant name",
"type": [
"string",
"null"
]
},
"id": {
"description": "Parameter id",
"type": "number"
},
"name": {
"description": "Pollutant code (e.g. \"pm25\")",
"type": "string"
}
},
"required": [
"id",
"name",
"displayName"
],
"type": "object"
},
"sensorId": {
"description": "Sensor id — use the corresponding locationId + parametersId to fetch this sensor's history via openaq_get_measurements",
"type": "number"
},
"unit": {
"description": "Unit for this value (e.g. \"µg/m³\", \"ppm\", \"ppb\"). Always read it — units differ across stations and pollutants; the value is meaningless without it.",
"type": "string"
},
"value": {
"description": "Measured concentration",
"type": "number"
}
},
"required": [
"parameter",
"value",
"unit",
"sensorId",
"datetimeUtc",
"datetimeLocal"
],
"type": "object"
},
"type": "array"
}
},
"type": "object"
}
},
{
"description": "Catalog of country-level coverage: id, OpenAQ country code, name, the date span of available station data (datetimeFirst/datetimeLast), and which parameters are measured anywhere in that country. The availability check before a regional sweep — answers \"which countries have NO2 monitoring?\" and tells you whether a country has recent data before you call openaq_find_locations. Coverage is uneven worldwide; this surfaces where measured data exists. Results come a page at a time (20 countries by default); totalCount is the full filtered count.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"limit": {
"default": 20,
"description": "Max countries to return (1–100). Default 20. Applied after query and parametersId, in OpenAQ catalog order.",
"maximum": 100,
"minimum": 1,
"type": "integer"
},
"page": {
"default": 1,
"description": "Which page of the filtered list to return (1-based). Default 1. With limit 20, page 2 returns countries 21–40. A page past the last one returns no countries and a notice naming the last page.",
"maximum": 9007199254740991,
"minimum": 1,
"type": "integer"
},
"parametersId": {
"description": "Only return countries that measure this parameter id somewhere (e.g. 2 = PM2.5 µg/m³) — the one-call answer to \"which countries have NO2 monitoring?\". Get ids from openaq_list_parameters; the same pollutant has several ids for different units. Composes with query.",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"type": "integer"
},
"query": {
"description": "Case-insensitive filter over the country catalog by code and name. A two-letter query matches an exact ISO 3166-1 alpha-2 code first (e.g. \"US\" → United States) and falls back to substrings when no code matches; longer queries match as substrings (e.g. \"united\", \"germany\"). Omit to page through the whole catalog.",
"type": "string"
}
},
"type": "object"
},
"name": "openaq_list_countries",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"countries",
"totalCount"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"cap": {
"description": "The limit that was applied.",
"type": "number"
},
"countries": {
"description": "Matching countries with coverage metadata.",
"items": {
"additionalProperties": false,
"description": "A country with its coverage span and measured parameters",
"properties": {
"code": {
"description": "OpenAQ country code: ISO 3166-1 alpha-2, or \"-99\" where OpenAQ has none — pass as iso to openaq_find_locations",
"type": "string"
},
"datetimeFirst": {
"description": "UTC timestamp of the earliest available measurement in this country (ISO 8601)",
"type": [
"string",
"null"
]
},
"datetimeLast": {
"description": "UTC timestamp of the most recent measurement — recent means the country has live coverage",
"type": [
"string",
"null"
]
},
"id": {
"description": "Country id (OpenAQ internal)",
"type": "number"
},
"name": {
"description": "Country name",
"type": "string"
},
"parameters": {
"description": "Parameters measured anywhere in this country — a coverage hint, not a per-station guarantee",
"items": {
"additionalProperties": false,
"description": "A parameter measured somewhere in this country",
"properties": {
"id": {
"description": "Parameter id measured somewhere in this country",
"type": "number"
},
"name": {
"description": "Pollutant code",
"type": "string"
},
"unit": {
"description": "Unit for this parameter id",
"type": "string"
}
},
"required": [
"id",
"name",
"unit"
],
"type": "object"
},
"type": "array"
}
},
"required": [
"id",
"code",
"name",
"datetimeFirst",
"datetimeLast",
"parameters"
],
"type": "object"
},
"type": "array"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode. Declared by this tool: `upstream_error`: OpenAQ /countries returned 5xx or an unreadable body on every retry. `rate_limited`: OpenAQ returned 429 — the request budget for this key is exhausted. `upstream_timeout`: OpenAQ /countries did not respond within the request timeout on every retry. `invalid_api_key`: OpenAQ returned 401 — the configured OPENAQ_API_KEY is missing, invalid, or revoked. Other values are possible when a failure originates below the handler.",
"examples": [
"upstream_error",
"rate_limited",
"upstream_timeout",
"invalid_api_key"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"notice": {
"description": "Guidance when the filters matched nothing, when more pages follow (the next page to request), or when the page is past the last one.",
"type": "string"
},
"shown": {
"description": "Number of countries returned on this page.",
"type": "number"
},
"totalCount": {
"description": "Countries matched after query and parametersId, across every page.",
"type": "number"
},
"truncated": {
"description": "True when more matching countries follow on later pages.",
"type": "boolean"
}
},
"type": "object"
}
},
{
"description": "Catalog of every measurable pollutant and its canonical unit: id, code, display name, unit, and a one-line description (pm25, pm10, o3, no2, so2, co, bc, and more). This is the unit-disambiguation reference — the same pollutant exists under several ids with different units (CO is id 4 in µg/m³, id 8 in ppm, id 102 in ppb), so use this to pick the exact parametersId for openaq_find_locations / openaq_get_readings / openaq_get_measurements and to interpret a reading's unit. A small bounded catalog fetched live from OpenAQ.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"pollutantsOnly": {
"default": false,
"description": "When true, exclude meteorological/auxiliary parameters (temperature, humidity, wind, pressure, particle-count channels) and return only air pollutants. Default false (full catalog).",
"type": "boolean"
},
"query": {
"description": "Case-insensitive filter over the bounded parameter catalog by code, display name, and description (e.g. \"pm\" for particulates, \"ozone\", \"co\"). Omit to list everything.",
"type": "string"
}
},
"type": "object"
},
"name": "openaq_list_parameters",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"parameters",
"totalCount"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode. Declared by this tool: `upstream_error`: OpenAQ /parameters returned 5xx or an unreadable body on every retry. `rate_limited`: OpenAQ returned 429 — the request budget for this key is exhausted. `upstream_timeout`: OpenAQ /parameters did not respond within the request timeout on every retry. `invalid_api_key`: OpenAQ returned 401 — the configured OPENAQ_API_KEY is missing, invalid, or revoked. Other values are possible when a failure originates below the handler.",
"examples": [
"upstream_error",
"rate_limited",
"upstream_timeout",
"invalid_api_key"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"notice": {
"description": "Guidance when the query matched nothing.",
"type": "string"
},
"parameters": {
"description": "Matching parameters. Multiple rows can share a name with different ids/units — pick the id whose unit you want.",
"items": {
"additionalProperties": false,
"description": "A measurable parameter with its canonical unit",
"properties": {
"description": {
"description": "One-line description of the pollutant",
"type": [
"string",
"null"
]
},
"displayName": {
"description": "Human-readable name (e.g. \"PM2.5\", \"O₃ mass\")",
"type": [
"string",
"null"
]
},
"id": {
"description": "Parameter id — the precise selector for the other tools (unit-specific)",
"type": "number"
},
"name": {
"description": "Pollutant code (e.g. \"pm25\", \"o3\", \"co\")",
"type": "string"
},
"unit": {
"description": "Canonical measurement unit for this id (e.g. \"µg/m³\", \"ppm\", \"ppb\"). The same pollutant code appears under multiple ids with different units.",
"type": "string"
}
},
"required": [
"id",
"name",
"displayName",
"unit",
"description"
],
"type": "object"
},
"type": "array"
},
"totalCount": {
"description": "Total parameters matched after filtering.",
"type": "number"
}
},
"type": "object"
}
}
]
}Verify it yourself
curl -s https://api.teppi.xyz/v1/evidence/sha256:0a5bfcd96b3b6af0306dbb370691d20beba3555439d8346e0e021f89c21737d0 | sha256sum