openaq-mcp-server

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['canvas_id'], 'properties': {'canvas_id': {'type': 'string', 'pattern': '^[A-Za-z0-9_-]{10}$', 'description': 'DataCanvas id returned by openaq_get_measurements â\x80\x94 minted when a series overflowed the inline preview, or the canvas_id you passed it.'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['tables']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['canvas_unavailable', 'canvas_not_found'], '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.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'notice': {'type': 'string', 'description': 'Guidance when the canvas holds no tables yet.'}, 'tables': {'type': 'array', 'items': {'type': 'object', 'required': ['name', 'rowCount', 'columns'], 'properties': {'name': {'type': 'string', 'description': 'Table name â\x80\x94 reference it in openaq_dataframe_query SQL.'}, 'columns': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Column names available for SELECT.'}, 'rowCount': {'type': 'number', 'description': 'Rows staged in this table.'}}, 'description': 'A staged measurement table with its columns', 'additionalProperties': False}, 'description': 'Tables currently staged on the canvas.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['canvas_id', 'sql'], 'properties': {'sql': {'type': 'string', '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.'}, 'canvas_id': {'type': 'string', 'pattern': '^[A-Za-z0-9_-]{10}$', 'description': 'DataCanvas id returned by openaq_get_measurements â\x80\x94 minted when a series overflowed the inline preview, or the canvas_id you passed it.'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['rows', 'rowCount']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'rows': {'type': 'array', 'items': {'type': 'object', 'propertyNames': {'type': 'string'}, 'additionalProperties': {}}, 'description': 'Result rows, at most 200. Every row here is also rendered in the text output â\x80\x94 the two surfaces carry the same set.'}, 'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['canvas_unavailable', 'canvas_not_found', 'missing_table'], '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.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'notice': {'type': 'string', 'description': 'How to reach the rest of the result when the row cap cut it short.'}, 'rowCount': {'type': 'number', '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.'}, 'truncated': {'type': 'boolean', '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.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'iso': {'type': 'string', 'pattern': '^(?:[A-Za-z]{2}|-99)$', '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.'}, 'bbox': {'type': 'string', 'pattern': '^(-?\\d+(\\.\\d+)?,){3}-?\\d+(\\.\\d+)?$', 'description': 'Bounding box as "minLon,minLat,maxLon,maxLat" (west,south,east,north), with minLon â\x89¤ maxLon and minLat â\x89¤ maxLat. Alternative to coordinates+radius for area sweeps. Results have no distance field (no center point).'}, 'page': {'type': 'integer', 'default': 1, 'maximum': 9007199254740991, 'minimum': 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â\x80\x93200. Distance ordering applies within a page, not across pages, so paging is for iso/bbox sweeps â\x80\x94 a near-me coordinates search should stay on page 1. A page past the last one fails with page_exhausted.'}, 'limit': {'type': 'integer', 'default': 20, 'maximum': 100, 'minimum': 1, 'description': 'Max stations to return (1â\x80\x93100). Default 20. Results are ordered by distance when searching by coordinates.'}, 'mobile': {'type': 'boolean', 'description': 'Mobility filter: true returns only mobile stations, false only fixed ones. Omit for both.'}, 'radius': {'type': 'integer', 'maximum': 25000, 'minimum': 1, 'description': 'Search radius in metres around coordinates (1â\x80\x9325000; the API hard-caps at 25000). Default 12000 (~12km). Requires coordinates â\x80\x94 a radius sent with only bbox or iso is rejected.'}, 'monitor': {'type': 'boolean', 'description': 'Station class filter: true returns only reference-grade monitors, false only low-cost sensors. Omit for both.'}, 'coordinates': {'type': 'string', 'pattern': '^-?\\d{1,3}(\\.\\d+)?,-?\\d{1,3}(\\.\\d+)?$', '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.'}, 'providersId': {'type': 'integer', 'maximum': 9007199254740991, 'description': "Only return stations from this OpenAQ provider (data network) id â\x80\x94 read it from a previous result's providerId (e.g. 119 = AirNow).", 'exclusiveMinimum': 0}, 'parametersId': {'type': 'integer', 'maximum': 9007199254740991, 'description': 'Only return stations that measure this parameter id (e.g. 2 = PM2.5 µg/m³). Get ids from openaq_list_parameters â\x80\x94 the same pollutant has several ids for different units. Narrows the station set; each returned station still lists all its sensors.', 'exclusiveMinimum': 0}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['locations', 'totalCount']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'cap': {'type': 'number', 'description': 'The limit that was applied.'}, 'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['no_locations_found', 'page_exhausted', 'no_search_scope', 'invalid_search_scope', 'upstream_error', 'rate_limited', 'upstream_timeout', 'invalid_api_key'], '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 â\x80\x94 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 â\x80\x94 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 â\x80\x94 the configured OPENAQ_API_KEY is missing, invalid, or revoked. Other values are possible when a failure originates below the handler.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'shown': {'type': 'number', 'description': 'Number of stations returned.'}, 'notice': {'type': 'string', 'description': 'Guidance on a full page: the next page to request, or how to narrow the search.'}, 'locations': {'type': 'array', 'items': {'type': 'object', 'required': ['id', 'name', 'locality', 'country', 'coordinates', 'distanceMeters', 'provider', 'providerId', 'isMonitor', 'isMobile', 'parameters', 'datetimeLast', 'datetimeFirst'], 'properties': {'id': {'type': 'number', 'description': 'Location id â\x80\x94 pass to openaq_get_readings / openaq_get_measurements'}, 'name': {'type': 'string', 'description': 'Station name'}, 'country': {'anyOf': [{'type': 'object', 'required': ['code', 'name'], 'properties': {'code': {'type': 'string', 'description': 'OpenAQ country code: ISO 3166-1 alpha-2, or "-99" where OpenAQ lists none'}, 'name': {'type': 'string', 'description': 'Country name'}}, 'additionalProperties': False}, {'type': 'null'}], 'description': 'Country the station is in. Null when OpenAQ lists none.'}, 'isMobile': {'type': 'boolean', 'description': 'True if the station is mobile (coordinates may vary over time)'}, 'locality': {'type': ['string', 'null'], 'description': 'Locality or metro area, when provided'}, 'provider': {'type': ['string', 'null'], 'description': 'Data provider / network (e.g. "AirNow", "OpenAQ LCS"). Null when OpenAQ lists none.'}, 'isMonitor': {'type': 'boolean', 'description': 'True for reference-grade government monitors; false for low-cost sensors. Reference monitors are more reliable for regulatory comparison.'}, 'parameters': {'type': 'array', 'items': {'type': 'object', 'required': ['id', 'name', 'unit', 'displayName'], 'properties': {'id': {'type': 'number', 'description': 'Parameter id â\x80\x94 use as parametersId in get_readings / get_measurements'}, 'name': {'type': 'string', 'description': 'Pollutant code (e.g. "pm25", "o3")'}, 'unit': {'type': 'string', 'description': 'Measurement unit for this sensor (e.g. "µg/m³", "ppm"). Units vary by sensor â\x80\x94 never assume.'}, 'displayName': {'type': ['string', 'null'], 'description': 'Human-readable pollutant name'}}, 'description': 'A parameter the station measures, with its sensor unit', 'additionalProperties': False}, 'description': 'Parameters this station measures, each with its sensor unit. The station has one sensor per parameter.'}, 'providerId': {'type': ['number', 'null'], 'description': 'OpenAQ provider id â\x80\x94 pass as providersId to restrict a search to this network. Null when OpenAQ lists no provider.'}, 'coordinates': {'anyOf': [{'type': 'object', 'required': ['latitude', 'longitude'], 'properties': {'latitude': {'type': 'number', 'description': 'Station latitude (decimal degrees)'}, 'longitude': {'type': 'number', 'description': 'Station longitude (decimal degrees)'}}, 'additionalProperties': False}, {'type': 'null'}], 'description': 'Station location. Null when OpenAQ lists no latitude or no longitude.'}, 'datetimeLast': {'anyOf': [{'type': 'object', 'required': ['utc', 'local'], 'properties': {'utc': {'type': 'string', 'description': 'Timestamp in UTC (ISO 8601)'}, 'local': {'type': 'string', 'description': "Timestamp in the station's local timezone"}}, 'additionalProperties': False}, {'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.'}, 'datetimeFirst': {'anyOf': [{'type': 'object', 'required': ['utc', 'local'], 'properties': {'utc': {'type': 'string', 'description': 'Timestamp in UTC (ISO 8601)'}, 'local': {'type': 'string', 'description': "Timestamp in the station's local timezone"}}, 'additionalProperties': False}, {'type': 'null'}], 'description': "Timestamp of the station's first available measurement."}, 'distanceMeters': {'type': ['number', 'null'], 'description': 'Distance from the query coordinates in metres. Null when searching by bbox or iso (no center point).'}}, 'description': 'A matching monitoring station with its sensors and data span', 'additionalProperties': False}, '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.'}, 'truncated': {'type': 'boolean', 'description': 'True when this page came back full (the limit was reached), so the next page may hold more stations.'}, 'totalCount': {'type': 'number', 'description': 'Stations counted through this page: (page â\x88\x92 1) Ã\x97 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.'}, 'totalCountIsLowerBound': {'type': 'boolean', 'description': 'True when this page came back full: at least totalCount stations match, and the next page may hold more.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['locationId', 'parametersId'], 'properties': {'limit': {'type': 'integer', 'default': 1000, 'maximum': 1000, 'minimum': 1, 'description': 'Max rows per page from the API (1â\x80\x931000). Default 1000. The tool pages internally up to the 5000-row pull ceiling.'}, 'canvas_id': {'type': 'string', 'pattern': '^[A-Za-z0-9_-]{10}$', '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 â\x80\x94 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': {'type': 'string', 'pattern': '^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}Z)?$', '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 â\x80\x94 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': {'type': 'integer', 'maximum': 9007199254740991, 'description': 'Station id from openaq_find_locations.', 'exclusiveMinimum': 0}, 'aggregation': {'enum': ['raw', 'hourly', 'daily'], 'type': 'string', '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.'}, 'datetimeFrom': {'type': 'string', 'pattern': '^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}Z)?$', '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 â\x80\x94 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': {'type': 'integer', 'maximum': 9007199254740991, '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 â\x80\x94 find_locations lists each station's parameters.", 'exclusiveMinimum': 0}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['location', 'parameter', 'sensorId', 'aggregation', 'series', 'rowCount', 'pulledCount', 'pullComplete', 'totalCount', 'effectiveRange']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'gaps': {'type': 'array', 'items': {'type': 'object', 'required': ['datetimeFrom', 'datetimeTo'], 'properties': {'datetimeTo': {'type': 'string', 'description': 'End of the missing interval, UTC'}, 'datetimeFrom': {'type': 'string', 'description': 'Start of the missing interval, UTC'}}, 'description': 'One missing interval', 'additionalProperties': False}, 'description': 'The first 20 missing intervals, oldest first. Omitted when gapCount is 0.'}, 'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', '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'], '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 â\x80\x94 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 â\x80\x94 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 â\x80\x94 the configured OPENAQ_API_KEY is missing, invalid, or revoked. Other values are possible when a failure originates below the handler."}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'notice': {'type': 'string', 'description': 'What limited this response or where the rest of it lives â\x80\x94 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': {'type': 'array', 'items': {'type': 'object', 'required': ['datetimeFrom', 'datetimeTo', 'value', 'summary', 'percentComplete', 'flagged'], 'properties': {'value': {'type': ['number', 'null'], '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 â\x80\x94 the bucket is kept so the series stays evenly spaced on the time axis'}, 'flagged': {'type': 'boolean', 'description': 'True if the source flagged this value (quality concern)'}, 'summary': {'anyOf': [{'type': 'object', 'required': ['min', 'median', 'max', 'avg', 'sd'], 'properties': {'sd': {'type': ['number', 'null'], 'description': 'Standard deviation â\x80\x94 null when only one reading in the bucket'}, 'avg': {'type': ['number', 'null'], 'description': 'Mean reading in the bucket'}, 'max': {'type': ['number', 'null'], 'description': 'Maximum reading in the bucket'}, 'min': {'type': ['number', 'null'], 'description': 'Minimum reading in the bucket'}, 'median': {'type': ['number', 'null'], 'description': 'Median reading in the bucket'}}, 'additionalProperties': False}, {'type': 'null'}], 'description': 'Per-bucket statistics â\x80\x94 present for hourly/daily, null for raw. Every field is null in a gap bucket'}, 'datetimeTo': {'type': 'string', 'description': 'Bucket end, UTC (ISO 8601)'}, 'datetimeFrom': {'type': 'string', 'description': 'Bucket start, UTC (ISO 8601)'}, 'percentComplete': {'type': ['number', 'null'], 'description': 'Coverage of the bucket as OpenAQ reports it â\x80\x94 observed readings as a percentage of expected ones. Low values flag gappy data. Usually 0â\x80\x93100, but it exceeds 100 when a bucket holds more readings than expected, e.g. 200 on the hour a DST fall-back repeats'}}, 'description': 'One bucket in the series, with its value and (for rollups) statistics', 'additionalProperties': False}, '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 â\x80\x94 gapCount and gaps report both. Every row here is also rendered in the text output. When truncated, this is a preview of pulledCount rows â\x80\x94 query canvasId for the rest.'}, 'canvasId': {'type': 'string', 'description': "DataCanvas id holding the staged series â\x80\x94 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': {'type': 'number', 'description': 'Missing intervals inside an hourly or daily series â\x80\x94 a span between buckets that do not touch, or a bucket with a null value, merged where contiguous â\x80\x94 counted over every pulled row, not only the preview. 0 when nothing is missing; absent for raw, whose rows follow no fixed cadence.'}, 'location': {'type': 'object', 'required': ['id', 'name', 'provider', 'providerId', 'timezone'], 'properties': {'id': {'type': 'number', 'description': 'Station id'}, 'name': {'type': 'string', 'description': 'Station name'}, 'provider': {'type': ['string', 'null'], 'description': 'Network that operates the station â\x80\x94 cite it alongside OpenAQ. Null when OpenAQ lists none.'}, 'timezone': {'type': ['string', 'null'], '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.'}, 'providerId': {'type': ['number', 'null'], 'description': 'Provider id, usable as providersId in openaq_find_locations. Null when OpenAQ lists none.'}}, 'description': 'Station the series came from', 'additionalProperties': False}, 'rowCount': {'type': 'number', 'description': 'Rows in this response (preview length when spilled)'}, 'sensorId': {'type': 'number', 'description': 'Resolved sensor id the series was pulled from'}, 'parameter': {'type': 'object', 'required': ['id', 'name', 'unit', 'displayName'], 'properties': {'id': {'type': 'number', 'description': 'Parameter id'}, 'name': {'type': 'string', 'description': 'Pollutant code'}, 'unit': {'type': 'string', 'description': 'Unit for every value in this series. The server does not convert units.'}, 'displayName': {'type': ['string', 'null'], 'description': 'Human-readable pollutant name'}}, 'description': "What was measured, resolved from the station's sensor", 'additionalProperties': False}, 'tableName': {'type': 'string', '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.'}, 'truncated': {'type': 'boolean', '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 â\x80\x94 canvasId reports whether the rows were staged, and pullComplete whether the pull itself finished.'}, 'totalCount': {'type': 'number', 'description': 'Rows in the full series for this range. A floor rather than an exact count when totalCountIsLowerBound is set; never below pulledCount.'}, 'aggregation': {'enum': ['raw', 'hourly', 'daily'], 'type': 'string', 'description': 'Bucketing applied'}, 'pulledCount': {'type': 'number', 'description': "Rows pulled from OpenAQ, at most 5000 â\x80\x94 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': {'type': 'boolean', '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 â\x80\x94 the rows past that point are in neither this response nor the canvas table, and the notice says how to reach them.'}, 'effectiveRange': {'type': 'object', 'required': ['datetimeFrom', 'datetimeTo'], 'properties': {'datetimeTo': {'type': ['string', 'null'], 'description': 'Upper bound sent to OpenAQ, UTC. Null when datetimeTo was omitted.'}, 'datetimeFrom': {'type': ['string', 'null'], 'description': 'Lower bound sent to OpenAQ, UTC. Null when datetimeFrom was omitted.'}}, 'description': "The range sent to OpenAQ as UTC instants â\x80\x94 date-only bounds expanded to the station's local day.", 'additionalProperties': False}, 'totalCountIsLowerBound': {'type': 'boolean', '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.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'locationId': {'type': 'integer', 'maximum': 9007199254740991, '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}, 'coordinates': {'type': 'string', 'pattern': '^-?\\d{1,3}(\\.\\d+)?,-?\\d{1,3}(\\.\\d+)?$', 'description': 'Fallback "latitude,longitude" when you do not have a locationId â\x80\x94 resolves to the nearest station (within 25km) that measures parametersId, then reads its latest values. Requires parametersId.'}, 'parametersId': {'type': 'integer', 'maximum': 9007199254740991, '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}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['location', 'readings']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', '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'], '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 â\x80\x94 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 â\x80\x94 the configured OPENAQ_API_KEY is missing, invalid, or revoked. Other values are possible when a failure originates below the handler.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'notice': {'type': 'string', '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.'}, 'location': {'type': 'object', 'required': ['id', 'name', 'coordinates', 'provider', 'providerId', 'timezone', 'distanceMeters', 'datetimeLast'], 'properties': {'id': {'type': 'number', 'description': 'Station id'}, 'name': {'type': 'string', 'description': 'Station name'}, 'provider': {'type': ['string', 'null'], 'description': 'Network that operates the station (e.g. "AirNow") â\x80\x94 cite it alongside OpenAQ. Null when OpenAQ lists none.'}, 'timezone': {'type': ['string', 'null'], 'description': 'IANA timezone of the station'}, 'providerId': {'type': ['number', 'null'], 'description': 'Provider id, usable as providersId in openaq_find_locations. Null when OpenAQ lists none.'}, 'coordinates': {'anyOf': [{'type': 'object', 'required': ['latitude', 'longitude'], 'properties': {'latitude': {'type': 'number', 'description': 'Station latitude (decimal degrees)'}, 'longitude': {'type': 'number', 'description': 'Station longitude (decimal degrees)'}}, 'additionalProperties': False}, {'type': 'null'}], 'description': 'Station coordinates. Null when OpenAQ lists no latitude or no longitude.'}, 'datetimeLast': {'anyOf': [{'type': 'object', 'required': ['utc', 'local'], 'properties': {'utc': {'type': 'string', 'description': 'Timestamp in UTC (ISO 8601)'}, 'local': {'type': 'string', 'description': "Timestamp in the station's local timezone"}}, 'additionalProperties': False}, {'type': 'null'}], 'description': 'Timestamp of the station\'s most recent measurement â\x80\x94 tells you whether "latest" is minutes or hours old before reading per-value timestamps. Null if the station has never reported.'}, 'distanceMeters': {'type': ['number', 'null'], 'description': 'Distance from query coordinates in metres, when resolved via coordinates; null when called by locationId'}}, 'description': 'The station these readings came from', 'additionalProperties': False}, 'readings': {'type': 'array', 'items': {'type': 'object', 'required': ['parameter', 'value', 'unit', 'sensorId', 'datetimeUtc', 'datetimeLocal'], 'properties': {'unit': {'type': 'string', 'description': 'Unit for this value (e.g. "µg/m³", "ppm", "ppb"). Always read it â\x80\x94 units differ across stations and pollutants; the value is meaningless without it.'}, 'value': {'type': 'number', 'description': 'Measured concentration'}, 'sensorId': {'type': 'number', 'description': "Sensor id â\x80\x94 use the corresponding locationId + parametersId to fetch this sensor's history via openaq_get_measurements"}, 'parameter': {'type': 'object', 'required': ['id', 'name', 'displayName'], 'properties': {'id': {'type': 'number', 'description': 'Parameter id'}, 'name': {'type': 'string', 'description': 'Pollutant code (e.g. "pm25")'}, 'displayName': {'type': ['string', 'null'], 'description': 'Human-readable pollutant name'}}, 'description': 'What was measured', 'additionalProperties': False}, 'datetimeUtc': {'type': 'string', 'description': 'Measurement time, UTC (ISO 8601)'}, 'datetimeLocal': {'type': 'string', 'description': "Measurement time in the station's local timezone"}}, 'description': 'Latest value for one sensor, with its pollutant and unit', 'additionalProperties': False}, 'description': 'Latest value per sensor. An old datetime means the station reports infrequently or is stale â\x80\x94 not that the value is current.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'page': {'type': 'integer', 'default': 1, 'maximum': 9007199254740991, 'minimum': 1, 'description': 'Which page of the filtered list to return (1-based). Default 1. With limit 20, page 2 returns countries 21â\x80\x9340. A page past the last one returns no countries and a notice naming the last page.'}, 'limit': {'type': 'integer', 'default': 20, 'maximum': 100, 'minimum': 1, 'description': 'Max countries to return (1â\x80\x93100). Default 20. Applied after query and parametersId, in OpenAQ catalog order.'}, 'query': {'type': 'string', '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" â\x86\x92 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.'}, 'parametersId': {'type': 'integer', 'maximum': 9007199254740991, 'description': 'Only return countries that measure this parameter id somewhere (e.g. 2 = PM2.5 µg/m³) â\x80\x94 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}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['countries', 'totalCount']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'cap': {'type': 'number', 'description': 'The limit that was applied.'}, 'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['upstream_error', 'rate_limited', 'upstream_timeout', 'invalid_api_key'], '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 â\x80\x94 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 â\x80\x94 the configured OPENAQ_API_KEY is missing, invalid, or revoked. Other values are possible when a failure originates below the handler.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'shown': {'type': 'number', 'description': 'Number of countries returned on this page.'}, 'notice': {'type': 'string', '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.'}, 'countries': {'type': 'array', 'items': {'type': 'object', 'required': ['id', 'code', 'name', 'datetimeFirst', 'datetimeLast', 'parameters'], 'properties': {'id': {'type': 'number', 'description': 'Country id (OpenAQ internal)'}, 'code': {'type': 'string', 'description': 'OpenAQ country code: ISO 3166-1 alpha-2, or "-99" where OpenAQ has none â\x80\x94 pass as iso to openaq_find_locations'}, 'name': {'type': 'string', 'description': 'Country name'}, 'parameters': {'type': 'array', 'items': {'type': 'object', 'required': ['id', 'name', 'unit'], 'properties': {'id': {'type': 'number', 'description': 'Parameter id measured somewhere in this country'}, 'name': {'type': 'string', 'description': 'Pollutant code'}, 'unit': {'type': 'string', 'description': 'Unit for this parameter id'}}, 'description': 'A parameter measured somewhere in this country', 'additionalProperties': False}, 'description': 'Parameters measured anywhere in this country â\x80\x94 a coverage hint, not a per-station guarantee'}, 'datetimeLast': {'type': ['string', 'null'], 'description': 'UTC timestamp of the most recent measurement â\x80\x94 recent means the country has live coverage'}, 'datetimeFirst': {'type': ['string', 'null'], 'description': 'UTC timestamp of the earliest available measurement in this country (ISO 8601)'}}, 'description': 'A country with its coverage span and measured parameters', 'additionalProperties': False}, 'description': 'Matching countries with coverage metadata.'}, 'truncated': {'type': 'boolean', 'description': 'True when more matching countries follow on later pages.'}, 'totalCount': {'type': 'number', 'description': 'Countries matched after query and parametersId, across every page.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'query': {'type': 'string', '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.'}, 'pollutantsOnly': {'type': 'boolean', '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).'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['parameters', 'totalCount']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['upstream_error', 'rate_limited', 'upstream_timeout', 'invalid_api_key'], '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 â\x80\x94 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 â\x80\x94 the configured OPENAQ_API_KEY is missing, invalid, or revoked. Other values are possible when a failure originates below the handler.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'notice': {'type': 'string', 'description': 'Guidance when the query matched nothing.'}, 'parameters': {'type': 'array', 'items': {'type': 'object', 'required': ['id', 'name', 'displayName', 'unit', 'description'], 'properties': {'id': {'type': 'number', 'description': 'Parameter id â\x80\x94 the precise selector for the other tools (unit-specific)'}, 'name': {'type': 'string', 'description': 'Pollutant code (e.g. "pm25", "o3", "co")'}, 'unit': {'type': 'string', 'description': 'Canonical measurement unit for this id (e.g. "µg/m³", "ppm", "ppb"). The same pollutant code appears under multiple ids with different units.'}, 'description': {'type': ['string', 'null'], 'description': 'One-line description of the pollutant'}, 'displayName': {'type': ['string', 'null'], 'description': 'Human-readable name (e.g. "PM2.5", "Oâ\x82\x83 mass")'}}, 'description': 'A measurable parameter with its canonical unit', 'additionalProperties': False}, 'description': 'Matching parameters. Multiple rows can share a name with different ids/units â\x80\x94 pick the id whose unit you want.'}, 'totalCount': {'type': 'number', 'description': 'Total parameters matched after filtering.'}}, 'additionalProperties': False}