Air Quality Programmatic APIs Geolocation API
The Geolocation API from Air Quality Programmatic APIs — 2 operation(s) for geolocation.
OpenAPI Specification
openapi: 3.1.0
info:
title: Air Quality Programmatic APIs Real-time Air Quality Tile Air Quality Programmatic APIs Real Time Air Quality Tile API Geolocation API
description: API providing real-time air quality data as map tiles.
version: 1.0.0
servers:
- url: https://tiles.aqicn.org/tiles
description: Production server
tags:
- name: Geolocation
paths:
/feed/geo:{lat};{lng}/:
get:
operationId: getAQIByGeoCoordinates
summary: Air Quality Programmatic APIs AQICN Get AQI by Geographic Coordinates
description: Retrieve real-time air quality data for the nearest monitoring station to given latitude and longitude coordinates.
tags:
- Geolocation
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
parameters:
- name: lat
in: path
required: true
description: Latitude coordinate
schema:
type: number
example: 39.9042
- name: lng
in: path
required: true
description: Longitude coordinate
schema:
type: number
example: 116.4074
- name: token
in: query
required: true
description: API authentication token
schema:
type: string
example: demo
responses:
'200':
description: Air quality data for nearest station
content:
application/json:
schema:
$ref: '#/components/schemas/AQIStation'
examples:
getAQIByGeoCoordinates200Example:
summary: Default getAQIByGeoCoordinates 200 response
x-microcks-default: true
value:
status: ok
data:
aqi: 45
idx: 8502
city:
name: Beijing, China
url: https://aqicn.org/city/beijing/
geo:
- 39.9042
- 116.4074
200_error:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/feed/ip/:
get:
operationId: getAQIByIP
summary: Air Quality Programmatic APIs AQICN Get AQI by IP Geolocation
description: Retrieve air quality data for the location nearest to the client's IP address using IP geolocation.
tags:
- Geolocation
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
parameters:
- name: token
in: query
required: true
description: API authentication token
schema:
type: string
example: demo
responses:
'200':
description: Air quality data for IP-geolocated nearest station
content:
application/json:
schema:
$ref: '#/components/schemas/AQIStation'
examples:
getAQIByIP200Example:
summary: Default getAQIByIP 200 response
x-microcks-default: true
value:
status: ok
data:
aqi: 32
idx: 5678
components:
schemas:
ForecastData:
type: object
description: Multi-day air quality and weather forecast
properties:
daily:
type: object
description: Daily forecasts by pollutant
properties:
pm25:
type: array
description: PM2.5 daily forecast values
items:
$ref: '#/components/schemas/ForecastDay'
pm10:
type: array
items:
$ref: '#/components/schemas/ForecastDay'
o3:
type: array
items:
$ref: '#/components/schemas/ForecastDay'
uvi:
type: array
items:
$ref: '#/components/schemas/ForecastDay'
StationData:
type: object
description: Station data including AQI and pollutant readings
properties:
aqi:
type: integer
description: Overall Air Quality Index value
example: 45
idx:
type: integer
description: Station ID in AQICN database
example: 8502
city:
$ref: '#/components/schemas/CityInfo'
time:
$ref: '#/components/schemas/TimeInfo'
iaqi:
$ref: '#/components/schemas/PollutantData'
forecast:
$ref: '#/components/schemas/ForecastData'
attributions:
type: array
description: Data source attributions
items:
$ref: '#/components/schemas/Attribution'
TimeInfo:
type: object
description: Timestamp information for the reading
properties:
s:
type: string
description: ISO 8601 timestamp of measurement
example: '2025-04-19 10:00:00'
tz:
type: string
description: Station timezone
example: +08:00
v:
type: integer
description: Unix timestamp
example: 1745056800
ForecastDay:
type: object
description: Single-day forecast value
properties:
avg:
type: integer
description: Average AQI for the day
example: 52
day:
type: string
description: Date string
example: '2025-04-20'
max:
type: integer
description: Maximum AQI for the day
example: 78
min:
type: integer
description: Minimum AQI for the day
example: 31
Attribution:
type: object
description: Data source attribution
properties:
url:
type: string
format: uri
description: Attribution URL
example: https://www.epa.gov/airnow
name:
type: string
description: Data source name
example: US EPA AirNow
ErrorResponse:
type: object
description: Error response
properties:
status:
type: string
example: error
data:
type: string
description: Error message
example: Invalid key
PollutantData:
type: object
description: Individual pollutant AQI values
properties:
pm25:
type: object
description: PM2.5 AQI reading
properties:
v:
type: number
example: 45
pm10:
type: object
description: PM10 AQI reading
properties:
v:
type: number
example: 32
no2:
type: object
description: Nitrogen dioxide AQI reading
properties:
v:
type: number
example: 12
o3:
type: object
description: Ozone AQI reading
properties:
v:
type: number
example: 28
so2:
type: object
description: Sulfur dioxide AQI reading
properties:
v:
type: number
example: 5
co:
type: object
description: Carbon monoxide AQI reading
properties:
v:
type: number
example: 8
AQIStation:
type: object
description: Air quality monitoring station with current readings
properties:
status:
type: string
description: Response status (ok or error)
example: ok
data:
$ref: '#/components/schemas/StationData'
CityInfo:
type: object
description: City and location information for the station
properties:
name:
type: string
description: City and station name
example: Beijing, China
url:
type: string
format: uri
description: Station URL on AQICN
example: https://aqicn.org/city/beijing/
geo:
type: array
description: Geographic coordinates [latitude, longitude]
items:
type: number
example:
- 39.9042
- 116.4074
securitySchemes:
ApiKeyAuth:
type: apiKey
in: query
name: token
description: API key for authentication