Tutorial: OpenAQ (Air Quality)

Environment

Data source: OpenAQ

Overview

OpenAQ (Air Quality) wraps OpenAQ, handling authentication, pagination, and rate limits for you. This tutorial covers all 4 tools with working code examples you can copy and run.

Prerequisites

Sign up at https://context.gnist.ai/signup for a free API key (100 calls/day).
Choose your integration method: MCP protocol or REST API.

Connect via MCP

Add to your MCP client config (Claude Desktop, Cursor, etc.):

MCP Config

{
  "mcpServers": {
    "gnist-openaq": {
      "url": "https://context.gnist.ai/mcp/openaq/",
      "headers": {
        "Gnist-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Tools (4)

`get_air_quality`

Get current air quality at the nearest monitoring station. Returns readings for PM2.5, PM10, O3, NO2, and other available pollutants, along with a derived US EPA AQI score and category. Args: lat: Latitude of the location (-90 to 90). lon: Longitude of the location (-180 to 180). Returns: Station details, per-pollutant measurements, AQI, and dominant pollutant. AQI is derived from PM2.5 using the US EPA formula. Returns null if the nearest station does not report PM2.5.

Parameter	Type	Required	Description
`lat`	number	required	Latitude of the location (-90 to 90).
`lon`	number	required	Longitude of the location (-180 to 180).

curl -X POST "https://context.gnist.ai/mcp/openaq/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_air_quality", "arguments": {"lat": 59.91, "lon": 10.75}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/openaq/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'lat': 59.91, 'lon': 10.75},
            'name': 'get_air_quality'}},
)
print(resp.json())

`get_aqi_summary`

Get city-level AQI summary with dominant pollutant. Finds the most recently updated monitoring station matching the city name and returns its current readings. Useful when you know the city but not the exact coordinates. Args: city: City name (e.g. "Oslo", "London", "New York"). Returns: Station name, AQI score, category, and per-pollutant measurements.

Parameter	Type	Required	Description
`city`	string	required	City name (e.g. "Oslo", "London", "New York").

curl -X POST "https://context.gnist.ai/mcp/openaq/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_aqi_summary", "arguments": {"city": "Oslo"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/openaq/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'city': 'Oslo'}, 'name': 'get_aqi_summary'}},
)
print(resp.json())

`get_air_quality_history`

Get PM2.5 readings from the nearest station over the last N hours. Useful for trend analysis — is air quality improving or worsening? Args: lat: Latitude of the location (-90 to 90). lon: Longitude of the location (-180 to 180). hours: Number of hours of history to retrieve (1–72, default 24). Returns: Station name, parameter, unit, and a time-series of PM2.5 readings. Returns an empty entries list if the nearest station has no PM2.5 sensor.

Parameter	Type	Required	Description
`lat`	number	required	Latitude of the location (-90 to 90).
`lon`	number	required	Longitude of the location (-180 to 180).
`hours`	integer	optional	Number of hours of history to retrieve (1–72, default 24). (default: `24`)

curl -X POST "https://context.gnist.ai/mcp/openaq/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_air_quality_history", "arguments": {"lat": 59.91, "lon": 10.75}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/openaq/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'lat': 59.91, 'lon': 10.75},
            'name': 'get_air_quality_history'}},
)
print(resp.json())

`report_feedback`

Report a bug, feature request, or general feedback for this data source. Use this when something doesn't work as expected, when you'd like a new feature, or when you have suggestions for improvement. Args: feedback: Describe the issue or suggestion. feedback_type: One of 'bug', 'feature_request', or 'general'.

Parameter	Type	Required	Description
`feedback`	string	required
`feedback_type`	string	optional	(default: `general`)

curl -X POST "https://context.gnist.ai/mcp/openaq/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "report_feedback", "arguments": {"feedback": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/openaq/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'feedback': 'example'}, 'name': 'report_feedback'}},
)
print(resp.json())

FAQ

What data does OpenAQ (Air Quality) provide?

Real-time and forecast air quality data including AQI, PM2.5, and pollutant levels. It exposes 4 tools: get_air_quality, get_aqi_summary, get_air_quality_history, report_feedback.

What do I need to get started?

A Gnist API key (free tier: 100 calls/day). Sign up at https://context.gnist.ai/signup.

What format does the OpenAQ (Air Quality) API return?

JSON, via either MCP protocol (JSON-RPC 2.0) or REST API.