openaq-mcp-server

openaq-mcp-server: find locations

openaq_find_locations

Read-onlyIdempotent

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.

Input Schema

TableJSON Schema

Name	Required	Description
`iso`	No	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`	No	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).
`page`	No	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.
`limit`	No	Max stations to return (1–100). Default 20. Results are ordered by distance when searching by coordinates.
`mobile`	No	Mobility filter: true returns only mobile stations, false only fixed ones. Omit for both.
`radius`	No	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.
`monitor`	No	Station class filter: true returns only reference-grade monitors, false only low-cost sensors. Omit for both.
`coordinates`	No	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`	No	Only return stations from this OpenAQ provider (data network) id — read it from a previous result's providerId (e.g. 119 = AirNow).
`parametersId`	No	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.

Output Schema

TableJSON Schema

Name	Required	Description
`cap`	No	The limit that was applied.
`error`	No	Present when the call failed. Absent on success.
`shown`	No	Number of stations returned.
`notice`	No	Guidance on a full page: the next page to request, or how to narrow the search.
`locations`	No	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`	No	True when this page came back full (the limit was reached), so the next page may hold more stations.
`totalCount`	No	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.
`totalCountIsLowerBound`	No	True when this page came back full: at least totalCount stations match, and the next page may hold more.

Schema Changelog

Changes observed during successful MCP inspections.

Changed14 schema fields changedSep 24, 2026

removedOutput schema / properties / locations / items / properties / coordinates / additionalProperties
```
Removed value: -false
```

addedOutput schema / properties / locations / items / properties / coordinates / anyOf

Added value: +[
+  {
+    "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"
+  }
+]

changedOutput schema / properties / locations / items / properties / coordinates / description

Previous value: -"Station location"New value: +"Station location. Null when OpenAQ lists no latitude or no longitude."

removedOutput schema / properties / locations / items / properties / coordinates / properties

Removed value: -{
-  "latitude": {
-    "description": "Station latitude (decimal degrees)",
-    "type": "number"
-  },
-  "longitude": {
-    "description": "Station longitude (decimal degrees)",
-    "type": "number"
-  }
-}

removedOutput schema / properties / locations / items / properties / coordinates / required
```
Removed value: -[
-  "latitude",
-  "longitude"
-]
```
removedOutput schema / properties / locations / items / properties / coordinates / type
```
Removed value: -"object"
```
removedOutput schema / properties / locations / items / properties / country / additionalProperties
```
Removed value: -false
```

addedOutput schema / properties / locations / items / properties / country / anyOf

Added value: +[
+  {
+    "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"
+  }
+]

changedOutput schema / properties / locations / items / properties / country / description

Previous value: -"Country the station is in"New value: +"Country the station is in. Null when OpenAQ lists none."

removedOutput schema / properties / locations / items / properties / country / properties

Removed value: -{
-  "code": {
-    "description": "OpenAQ country code: ISO 3166-1 alpha-2, or \"-99\" where OpenAQ lists none",
-    "type": "string"
-  },
-  "name": {
-    "description": "Country name",
-    "type": "string"
-  }
-}

removedOutput schema / properties / locations / items / properties / country / required
```
Removed value: -[
-  "code",
-  "name"
-]
```
removedOutput schema / properties / locations / items / properties / country / type
```
Removed value: -"object"
```

changedOutput schema / properties / locations / items / properties / provider / description

Previous value: -"Data provider / network (e.g. \"AirNow\", \"OpenAQ LCS\")"New value: +"Data provider / network (e.g. \"AirNow\", \"OpenAQ LCS\"). Null when OpenAQ lists none."

changedOutput schema / properties / locations / items / properties / provider / type
```
Previous value: -"string"New value: +[
+  "string",
+  "null"
+]
```

Changed23 schema fields changedSep 24, 2026

changedInput schema / properties / bbox / description

Previous value: -"Bounding box as \"minLon,minLat,maxLon,maxLat\" (west,south,east,north). Alternative to coordinates+radius for area sweeps. Results have no distance field (no center point)."New value: +"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)."

changedInput schema / properties / iso / description

Previous value: -"Restrict to a country by ISO 3166-1 alpha-2 code (e.g. \"US\", \"IN\", \"DE\"). Combine with bbox/coordinates to scope, or use alone for a country-wide list. Discover coverage with openaq_list_countries."New value: +"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."

removedInput schema / properties / iso / maxLength
```
Removed value: -2
```
removedInput schema / properties / iso / minLength
```
Removed value: -2
```
addedInput schema / properties / iso / pattern
```
Added value: +"^(?:[A-Za-z]{2}|-99)$"
```

addedInput schema / properties / mobile

Added value: +{
+  "description": "Mobility filter: true returns only mobile stations, false only fixed ones. Omit for both.",
+  "type": "boolean"
+}

addedInput schema / properties / monitor

Added value: +{
+  "description": "Station class filter: true returns only reference-grade monitors, false only low-cost sensors. Omit for both.",
+  "type": "boolean"
+}

changedInput schema / properties / page / description

Previous value: -"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."New value: +"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."

addedInput schema / properties / parametersId / exclusiveMinimum
```
Added value: +0
```
removedInput schema / properties / parametersId / minimum
```
Removed value: --9007199254740991
```

addedInput schema / properties / providersId

Added value: +{
+  "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"
+}

removedInput schema / properties / radius / default
```
Removed value: -12000
```

changedInput schema / properties / radius / description

Previous value: -"Search radius in metres around coordinates (1–25000; the API hard-caps at 25000). Default 12000 (~12km). Only used with coordinates."New value: +"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."

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `no_locations_found`: No monitoring stations match the given area or filters. `no_search_scope`: None of coordinates, bbox, or iso was provided. `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."New value: +"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."

changedOutput schema / properties / error / properties / data / properties / reason / examples

Previous value: -[
-  "no_locations_found",
-  "no_search_scope",
-  "upstream_error",
-  "rate_limited",
-  "upstream_timeout",
-  "invalid_api_key"
-]New value: +[
+  "no_locations_found",
+  "page_exhausted",
+  "no_search_scope",
+  "invalid_search_scope",
+  "upstream_error",
+  "rate_limited",
+  "upstream_timeout",
+  "invalid_api_key"
+]

changedOutput schema / properties / locations / description

Previous value: -"Matching stations. Empty array means no monitoring coverage for the query — NOT clean air. Widen the radius, try openaq_list_countries, or use the modeled open-meteo air-quality tool."New value: +"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."

changedOutput schema / properties / locations / items / properties / country / properties / code / description

Previous value: -"ISO 3166-1 alpha-2 country code"New value: +"OpenAQ country code: ISO 3166-1 alpha-2, or \"-99\" where OpenAQ lists none"

addedOutput schema / properties / locations / items / properties / providerId

Added value: +{
+  "description": "OpenAQ provider id — pass as providersId to restrict a search to this network. Null when OpenAQ lists no provider.",
+  "type": [
+    "number",
+    "null"
+  ]
+}

changedOutput schema / properties / locations / items / required

Previous value: -[
-  "id",
-  "name",
-  "locality",
-  "country",
-  "coordinates",
-  "distanceMeters",
-  "provider",
-  "isMonitor",
-  "isMobile",
-  "parameters",
-  "datetimeLast",
-  "datetimeFirst"
-]New value: +[
+  "id",
+  "name",
+  "locality",
+  "country",
+  "coordinates",
+  "distanceMeters",
+  "provider",
+  "providerId",
+  "isMonitor",
+  "isMobile",
+  "parameters",
+  "datetimeLast",
+  "datetimeFirst"
+]

changedOutput schema / properties / notice / description

Previous value: -"Guidance when OpenAQ reports a lower-bound total without the result set hitting the limit."New value: +"Guidance on a full page: the next page to request, or how to narrow the search."

changedOutput schema / properties / totalCount / description

Previous value: -"Total matching stations before the limit. A floor (not an exact count) when totalCountIsLowerBound is true."New value: +"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."

changedOutput schema / properties / totalCountIsLowerBound / description

Previous value: -"True when OpenAQ reported a lower bound (\">N\"): totalCount is a floor and more stations match than the count shown."New value: +"True when this page came back full: at least totalCount stations match, and the next page may hold more."

changedOutput schema / properties / truncated / description

Previous value: -"True when the station list was capped at the limit."New value: +"True when this page came back full (the limit was reached), so the next page may hold more stations."

Changed6 schema fields changedSep 20, 2026
- removedOutput schema / properties / locations / items / properties / distanceMeters / anyOf
```
Removed value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / locations / items / properties / distanceMeters / type
```
Added value: +[
+  "number",
+  "null"
+]
```
- removedOutput schema / properties / locations / items / properties / locality / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / locations / items / properties / locality / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / properties / locations / items / properties / parameters / items / properties / displayName / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / locations / items / properties / parameters / items / properties / displayName / type
```
Added value: +[
+  "string",
+  "null"
+]
```

Changed6 schema fields changedAug 25, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / anyOf

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "locations",
+      "totalCount"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / error

Added value: +{
+  "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. `no_search_scope`: None of coordinates, bbox, or iso was provided. `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",
+            "no_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"
+}

removedOutput schema / required

Removed value: -[
-  "locations",
-  "totalCount"
-]

Changed1 schema field changedJul 26, 2026

addedInput schema / properties / page

Added value: +{
+  "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.",
+  "maximum": 9007199254740991,
+  "minimum": 1,
+  "type": "integer"
+}

Changed3 schema fields changedJul 1, 2026

addedOutput schema / properties / notice

Added value: +{
+  "description": "Guidance when OpenAQ reports a lower-bound total without the result set hitting the limit.",
+  "type": "string"
+}

changedOutput schema / properties / totalCount / description

Previous value: -"Total matching stations before the limit."New value: +"Total matching stations before the limit. A floor (not an exact count) when totalCountIsLowerBound is true."

addedOutput schema / properties / totalCountIsLowerBound

Added value: +{
+  "description": "True when OpenAQ reported a lower bound (\">N\"): totalCount is a floor and more stations match than the count shown.",
+  "type": "boolean"
+}

First observedJun 16, 2026

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already signal read-only, idempotent, and open-world behavior, and the description adds meaningful non-obvious context: stations are physical rather than modeled, coverage is uneven, an absence of stations does not mean clean air, and each returned station lists only the parameters it actually measures. These behavioral caveats materially affect how an agent interprets results.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The main description is compact and front-loaded: the primary action and query modes appear first, followed by return contents, workflow hint, and the important coverage caveat. Each sentence adds distinct value, and the alternative-tool routing is placed at the end without bloating the core purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's high complexity (10 optional parameters, multiple search modes, an output schema, and sibling tools), the description plus schema is fully sufficient for an agent to select, invoke, and interpret the tool. It covers the result shape, the station-id handoff to downstream tools, the physical-vs-modeled distinction, and the key caveat about data absence.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already documents all 10 parameters with 100% coverage, including formats, defaults, constraints, and cross-parameter rules. The description's mention of 'one parameter, one station class... or one provider network' is a high-level restatement of parametersId, monitor/mobile, and providersId rather than new semantic information, so it does not exceed the schema-driven baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Find') with a precise resource ('air-quality monitoring stations') and enumerates the exact query modes: near a point, within a bounding box, or by country. It also differentiates physical-sensor stations from modeled data and names the downstream tools that consume the returned location id, leaving no ambiguity about what this tool is for.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly positions this as the required first step before openaq_get_readings and openaq_get_measurements, and it names an alternative tool (open-meteo-mcp-server air-quality) for dense modeled coverage. This gives an agent clear routing guidance beyond the raw schema.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All openaq-mcp-server tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.