全国城市空气质量查询 接口整理与使用教程说明本文基于公开文档与文章整理未对每个接口做真实请求实测接口可用性以公开文档为准集成前请自行验证。文中所有 Key 均以YOUR_APPKEY/your_token占位请替换为你自己的凭证。写在前面做城市空气质量AQI、PM2.5、PM10、SO₂、NO₂、O₃、CO 等相关功能时通常会遇到几类来源综合 API 市场、天气服务商、按量计费的数据平台。它们的能力边界、鉴权方式、返回结构差异不小直接选错会拖慢集成。本文把市面上能找到、且写法可考的「全国城市空气质量查询」类接口做个梳理逐源给出请求地址、参数、返回示例与注意事项并附一份多源降级的参考实现。重点提醒部分免费接口存在调用档位限制、更新粒度差异、小地区回溯上级城市等细节集成前务必自行发一次请求验证字段与配额。1. 接口总览接口 / 来源请求地址示例说明HTTPS编码需要 Key来源类型易源 ShowAPI 全国城市空气质量查询104-42 / 104-41https://route.showapi.com/104-42?appKeyYOUR_APPKEY按城市查询 / 全国排行榜覆盖约 367 城是form-urlencoded是appKeyAPI 市场和风天气 QWeather 实时空气质量https://{your-api-host}/airquality/v1/current/{lat}/{lon}全球覆盖1×1km 精度按经纬度查询是JSON是JWT Bearer天气服务商天聚数行 TianAPI 空气质量指数https://apis.tianapi.com/aqi/index?keyYOUR_APPKEY全国 300 城市会员免费档可用是utf-8 JSON是key数据平台聚合数据 空气质量附录以官方文档为准商业套餐首次申请送试用次数是JSON是数据平台APISpace / 阿里云云市场「全国城市空气质量查询」https://route.showapi.com/104-42?appKeyYOUR_APPKEY与易源 104 同一底层接口属转售渠道是JSON是转售渠道2. 易源 ShowAPI 全国城市空气质量查询gateway 104一句话定位一个面向国内城市的空气质量查询接口提供「按城市查询104-42」与「全国城市空气质量排行榜104-41」两个接入点注册后默认可免费调用设有防滥用档位限制。请求示例104-42 按城市查询POST/GET 均可curl -X POST https://route.showapi.com/104-42?appKeyYOUR_APPKEY \ -H content-type: application/x-www-form-urlencoded \ -d area%E6%89%BF%E5%BE%B7返回示例104-42已截取关键字段{ showapi_res_code: 0, showapi_res_error: , showapi_res_body: { so2: 22, o3: 102, pm2_5: 63, primary_pollutant: 颗粒物(PM10), ct: 2018-04-18 11:30:00.000, num: 347, co: 1.2, area: 承德, no2: 43, aqi: 146, quality: 轻度污染, pm10: 239, o3_8h: 51, ret_code: 0 } }排行榜接入点104-41无查询参数返回showapi_res_body.list[]每项含area、aqi、quality、pm2_5、pm10、co、no2、o3、o3_8h、so2、primary_pollutant、area_code、num、ct。注意事项业务数据统一封装在showapi_res_body中showapi_res_code为 0 表示系统级成功ret_code为 0 表示业务成功。小地区规则国家仅公布约 370 个主要城市数据查询小地区如「双桥镇」会返回其所属上级主要城市如「承德」的数据。更新频率约为每半小时具体调用档位、QPS 以控制台配置为准。需自备 appKey在 ShowAPI 控制台获取本文仅按官方文档整理接入写法未返回真实业务数据。集成前建议阅读官方使用条款万维易源-使用向导3. 和风天气 QWeather 实时空气质量一句话定位全球范围的实时空气质量接口精度约 1×1 公里按经纬度返回 AQI、污染物浓度、健康建议适合需要国际覆盖或精细定位的场景。请求示例curl -X GET --compressed \ -H Authorization: Bearer your_token \ https://your-api-host/airquality/v1/current/39.92/116.41说明your-api-host为你在和风天气控制台分配到的 API Hostyour_token为 JWT 身份认证令牌。返回示例已截取关键字段{ metadata: { tag: d75a3232..., attributions: [https://developer.qweather.com/attribution.html] }, indexes: [ { code: us-epa, name: AQI (US), aqi: 46, level: 1, category: Good, primaryPollutant: { code: pm2p5, name: PM 2.5, fullName: Fine particulate matter (2.5µm) }, health: { effect: No health effects., advice: { generalPopulation: Everyone can continue their outdoor activities normally., sensitivePopulation: Everyone can continue their outdoor activities normally. } } } ], pollutants: [ { code: pm2p5, name: PM 2.5, concentration: { value: 11.0, unit: μg/m3 } }, { code: pm10, name: PM 10, concentration: { value: 12.0, unit: μg/m3 } }, { code: no2, name: NO2, concentration: { value: 6.77, unit: ppb } }, { code: o3, name: O3, concentration: { value: 0.02, unit: ppb } }, { code: co, name: CO, concentration: { value: 0.25, unit: ppm } } ] }注意事项使用路径参数latitude/longitude十进制最多两位小数按经纬度而非城市名查询。返回结构同时给出多种 AQI 标准us-epa、qaqicategory为英文类别如Good/Excellent与国内「优/良/轻度污染」六级中文分类不同前端展示需做映射。用Authorization: BearerJWT 鉴权归因信息attributions需与数据一同展示。官方文档实时空气质量 | 空气质量 | 和风天气开发者服务4. 天聚数行 TianAPI 空气质量指数aqi/index一句话定位国内城市空气质量查询接口覆盖全国 300 城市普通会员每日有免费调用额度接入简单、按地区名查询。请求示例curl -X GET https://apis.tianapi.com/aqi/index?keyYOUR_APPKEYarea%E4%B8%8A%E6%B5%B7返回示例{ msg: success, code: 200, result: { co: 0.4, o3: 89, aqi: 113, no2: 21, num: 330, so2: 7, area: 上海, pm10: 175, time: 2020-03-19 14:00:34.778, o3_8h: 83, pm2_5: 22, quality: 轻度污染, area_code: shanghai, primary_pollutant: 颗粒物(PM10) } }注意事项必填参数key你的 ApiKey、area地区名如「上海」。返回包裹在result中code为 200 表示成功并计费非 200 为错误如 150 可用次数不足、230 密钥无效、250 数据为空等。会员免费档普通会员每日 100 次免费小地区同样回溯到上级城市。官方 OpenAPIhttps://www.tianapi.com/openapi/aqi.json5. 横向对比事实对照维度易源 ShowAPI 104和风天气 QWeather天聚数行 TianAPI是否需要 Key是appKey是JWT Bearer是key查询方式按城市名 / 排行榜按经纬度按城市名返回格式JSONshowapi_res_body 包裹JSONindexes/pollutantsJSONresult 包裹HTTPS是是是编码form-urlencodedJSONutf-8 JSON覆盖范围国内约 367 城全球国内 300 城免费额度注册默认可免费有档位限制按套餐普通会员每日免费额度小地区处理回溯上级城市按坐标就近回溯上级城市各有取舍没有全能最优要国内城市名直查且免费起步易源 / 天聚数行更顺手要全球覆盖或精细经纬度定位和风天气更合适。按你自己的成本与精度需求选。6. 生产环境参考实现多源降级下面是一份 Python 参考实现把三个来源视为对等节点按顺序尝试某个来源失败网络错误、鉴权失败、字段缺失就切换到下一个。各来源的 Key、Host 由调用方配置。import os, json, urllib.parse, urllib.request def _get(url, dataNone, headersNone, timeout8): req urllib.request.Request(url, datadata, headersheaders or {}) with urllib.request.urlopen(req, timeouttimeout) as r: return json.loads(r.read().decode(utf-8)) # 1) 易源 ShowAPI 按城市查询 def from_showapi(area, appkey): url fhttps://route.showapi.com/104-42?appKey{appkey} body urllib.parse.urlencode({area: area}).encode(utf-8) headers {content-type: application/x-www-form-urlencoded} d _get(url, databody, headersheaders) b d.get(showapi_res_body, {}) if str(d.get(showapi_res_code)) ! 0 or str(b.get(ret_code)) ! 0: raise ValueError(d.get(showapi_res_error) or showapi business fail) return { source: showapi, area: b.get(area), aqi: b.get(aqi), quality: b.get(quality), pm2_5: b.get(pm2_5), pm10: b.get(pm10), primary_pollutant: b.get(primary_pollutant), } # 2) 和风天气 按经纬度 def from_qweather(lat, lon, host, token): url fhttps://{host}/airquality/v1/current/{lat}/{lon} d _get(url, headers{Authorization: fBearer {token}}) idx next((x for x in d.get(indexes, []) if x.get(code) us-epa), {}) pol {p[code]: p.get(concentration, {}).get(value) for p in d.get(pollutants, [])} return { source: qweather, aqi: idx.get(aqi), category: idx.get(category), primary_pollutant: (idx.get(primaryPollutant) or {}).get(name), pm2_5: pol.get(pm2p5), pm10: pol.get(pm10), } # 3) 天聚数行 按城市名 def from_tianapi(area, key): url fhttps://apis.tianapi.com/aqi/index?key{key}area{urllib.parse.quote(area)} d _get(url) if d.get(code) ! 200: raise ValueError(d.get(msg)) b d[result] return { source: tianapi, area: b.get(area), aqi: b.get(aqi), quality: b.get(quality), pm2_5: b.get(pm2_5), pm10: b.get(pm10), primary_pollutant: b.get(primary_pollutant), } def query_air_quality(area, latNone, lonNone): 多源降级城市名优先易源/天聚有经纬度再试和风。 attempts [] if os.getenv(SHOWAPI_KEY): attempts.append(lambda: from_showapi(area, os.environ[SHOWAPI_KEY])) if lat and lon and os.getenv(QWEATHER_HOST) and os.getenv(QWEATHER_TOKEN): attempts.append(lambda: from_qweather(lat, lon, os.environ[QWEATHER_HOST], os.environ[QWEATHER_TOKEN])) if os.getenv(TIANAPI_KEY): attempts.append(lambda: from_tianapi(area, os.environ[TIANAPI_KEY])) last None for fn in attempts: try: return fn() except Exception as e: last e continue raise last or RuntimeError(no source configured) if __name__ __main__: # 仅作结构演示需先配置环境变量 KEY/HOST/TOKEN try: print(query_air_quality(上海, lat31.23, lon121.47)) except Exception as e: print(all sources failed:, e)7. 踩坑清单免费≠无限易源、天聚数行都有每日/档位额度高并发或批量查询前先确认配额避免线上限流。小地区无独立数据按城市名查询时乡镇级地名会回溯到上级主要城市展示时要说明口径。返回结构各不相同易源用showapi_res_body、天聚数行用result、和风用indexes/pollutants前端务必分别做字段映射与存在性校验。AQI 标准不一致和风同时给出us-epa与qaqi类别为英文国内接口多为中文六级优/良/轻度污染…跨源展示需统一口径。Key 安全appKey / key / token 应放在服务端不要在前端明文暴露。更新粒度多数接口约每半小时更新不要拿它做逐分钟级实时展示。8. 附录补充说明聚合数据 空气质量id 33商业数据平台支持全国大部分城市、每小时更新首次申请送 20 次试用完整请求地址、参数与返回示例以官方文档 空气质量_空气质量API接口_标准化API接口_聚合数据 - 天聚地合 为准本文未展开接入写法。APISpace / 阿里云云市场「全国城市空气质量查询」其底层即易源 ShowAPI 104同为route.showapi.com/104-42接入点属转售渠道可作为易源 Key 的另一获取入口。Google Air Quality API全球覆盖、按量计费需 GCP 账号与计费适合出海场景集成前请查阅官方文档。以上来源均需自备 Key 或完整阅读官方文档后方可接入本文未做真实请求实测不对其可用性、稳定性、合规性作保证。9. 常见问题 FAQ问有没有完全免费、不需要 Key 的全国空气质量查询接口答没有真正「零 Key 且稳定」的公开接口。易源、天聚数行等有免费额度但仍需注册获取 Key纯公开页面如环境监测总站多为网页展示直接调用常需自行解析。问按城市名查不到小县城怎么办答国家仅公布约 370 个主要城市数据多数接口查询乡镇级地名会返回其所属上级主要城市的数据可改用上级城市名查询并注明口径。问易源 104 和天聚数行 TianAPI 返回结构一样吗答不一样。易源数据在showapi_res_body内天聚数行在result内字段命名相近但包裹层级不同需分别解析。问和风天气的 AQI 为什么是英文 Good / Excellent答和风返回多种 AQI 标准category为英文类别国内常用中文六级分类跨源展示时需做映射。问这些接口需要 HTTPS 吗答三个主要来源都支持 HTTPS生产环境应始终使用 HTTPS 传输 Key 与数据。问返回里的 aqi、pm2_5 是数字还是字符串答易源与天聚数行的数值字段多为字符串如146使用前按需做类型转换再参与运算。问Key 可以放在前端页面里吗答不建议。appKey / key / token 应放在服务端前端只调用你自己的后端避免密钥泄露与被盗刷。问数据多久更新一次答易源约每半小时更新天聚数行、和风按各自数据源粒度均不适合做逐分钟级实时展示。问调用失败怎么排查答先看系统级状态码易源showapi_res_code、天聚数行code再看业务码ret_code/code常见为 Key 无效、参数缺失、额度不足或限流。问能做全国城市空气质量排行榜吗答可以易源 104-41 接入点直接返回全国城市排行列表其他来源多按单城市查询需自行聚合。问多源之间怎么选优先级答没有固定最优。国内城市名直查优先易源 / 天聚数行全球或经纬度定位用和风生产环境可做多源降级互为备份。问本文里的接口都实测过吗答没有。本文基于公开文档与文章整理未做真实请求实测接口可用性、字段与配额以各官方文档为准集成前请自行验证。