全国城市空气质量查询 API 接口服务教程

本文为面向开发者、企业与系统集成商的客观技术教程，介绍基于阿里云云市场提供的「全国城市空气质量查询」标准化 API 接口能力，涵盖接口参数、返回字段、接入示例、计费与能力边界等，便于快速评估与集成。

全国城市空气质量查询 API 是面向全行业企业、开发者、系统服务商的通用数据接口服务，提供标准化、高稳定、高并发的空气质量数据处理与能力调用，适用于环境监测、智能硬件、交通出行、互联网资讯、企业 ERP、小程序/APP 等多场景，支持多语言快速接入、在线调试、批量调用。

一、技能简介

全国城市空气质量查询 API 是由阿里云云市场提供的标准化数据接口服务，面向开发者、企业与系统集成商开放。该接口支持查询全国最多 367 个城市的实时空气质量数据，覆盖空气质量指数（AQI）、PM2.5、PM10、二氧化硫、二氧化氮、臭氧、一氧化碳等多项污染物浓度，并给出空气质量类别与首要污染物。数据约每半小时更新，提供城市空气质量排行榜与按城市查询两种接入方式，广泛适用于环境监测、智能硬件、交通出行、互联网资讯等场景。接口采用标准 HTTP/JSON 协议，支持 POST/GET 调用，并提供多语言示例与 MCP / OpenAPI 接入能力，便于快速集成。

二、核心亮点

• 全国广覆盖：支持查询全国最多 367 个城市的空气质量数据，覆盖面广。
• 指标维度全：返回 AQI、PM2.5、PM10、SO₂、NO₂、O₃、CO 浓度及空气质量类别、首要污染物，满足多维分析。
• 更新及时：数据约每半小时刷新一次，保障时效性。
• 双接入点：提供「全国城市空气质量排行榜」与「按城市查询」两种能力，兼顾排行与定点查询。
• 标准协议：基于 HTTP/JSON，支持 POST/GET，易于对接各类技术栈。
• 多种接入形态：除标准 API 外，还提供 MCP 服务与 OpenAPI 3.0 文档，可被 AI Agent 与主流 API 工具直接消费。
• 免费试用门槛低：提供免费试用配额与多档阶梯套餐，按量付费、成本可预期。
• 多语言示例完备：提供 Python / Java / PHP / JS 示例，降低接入成本。

三、主要用途

空气质量数据在多个行业具有明确落地价值：

• 环境监测与公众服务：为环保类应用、政务大屏提供城市空气质量排行与等级展示。
• 智能硬件与可穿戴设备：净化器、空气检测仪联动外部空气质量数据，自动调节运行模式。
• 交通出行与地图导航：在出行、导航产品中提示目的地空气质量，辅助路线与出行建议。
• 互联网资讯与内容运营：资讯、天气、生活类站点嵌入空气质量模块，提升内容丰富度。
• 企业 ERP 与内部系统：工厂、园区将空气质量纳入健康职业卫生管理看板，可通过 ERP 对接空气质量 API 打通业务系统。
• 小程序 / APP 轻量集成：通过小程序空气质量接口快速上线查询功能。
• 企业级集成：企业级空气质量接口还可与数据中台、可视化大屏集成，形成统一的环境数据底座。

四、功能特点

五、操作流程

5.1 接入步骤

1. 注册并获取密钥：在阿里云云市场开通服务，获取 AppKey（或 APPCODE）调用凭证。
2. 选择接入点：按需选择「排行榜（104-41）」或「按城市查询（104-42）」。
3. 构造请求：以 POST/GET 方式请求 route.showapi.com/104-xx?appKey=YOUR_APPKEY，按接口填写参数（如 area）。
4. 解析返回：读取 HTTP 200 响应中的 showapi_res_body 业务对象，提取 AQI、污染物等指标。
5. 集成与监控：将字段映射至业务系统，结合调用配额与错误码做重试与告警。

5.2 调用流程示意

六、实际案例

以下为基于真实返回结构的典型应用场景示意。

场景一 · 城市空气质量排行榜：调用 104-41 接入点，返回全国最多 367 个城市空气质量排行列表，可直接用于环保大屏、资讯站点展示。示例返回中甘孜州 AQI 为 18、质量类别为「优」，适合做清新城市榜单。

场景二 · 按城市定点查询：调用 104-42 接入点并传入 area=双桥镇，系统按规则返回其上级主要城市「承德」的空气质量（AQI 146、轻度污染、首要污染物为颗粒物 PM10），体现小地区自动回溯上级城市的定位能力。

场景三 · 智能硬件联动：空气净化器或天气类 APP 定时拉取目标城市 AQI 与 PM2.5，当 AQI 超过阈值时推送提醒或自动切换运行模式，实现数据驱动的健康管理。

七、在线运行实录

7.1 参数设计

为验证「按城市查询」能力，设计如下创意请求：查询旅游城市「丽江」的实时空气质量，关注 AQI、PM2.5 与首要污染物，用于出行前健康提示。

• 接入点：104-42
• 参数：area = 丽江
• 方法：POST

7.2 运行过程

请求以异步方式提交，系统返回任务受理状态后进入数据处理阶段；从受理到返回结果通常耗时在秒级（以控制台实时配置为准）。返回的业务对象中包含 ret_code、aqi、quality、pm2_5、primary_pollutant 等字段。

7.3 结果解读

返回示例（结构示意）：

{
   
  "showapi_res_code": 0,
  "showapi_res_error": "",
  "showapi_res_body": {
   
    "ret_code": 0,
    "area": "丽江",
    "aqi": "23",
    "quality": "优",
    "pm2_5": "12",
    "primary_pollutant": "",
    "ct": "2025-01-06 13:11:50.500"
  }
}

结果表明丽江空气质量为「优」，AQI 23、PM2.5 12，首要污染物为空，适合出行。该结构可直接驱动前端展示与提醒逻辑。

八、接口接入示例 & 完整返回字段样例

下面给出空气质量在线调用接口的四种主流语言示例，开发者可直接替换为真实 AppKey 后调试。

8.1 Python

import urllib.request
import urllib.parse

url = "https://route.showapi.com/104-42?appKey=YOUR_APPKEY"
data = urllib.parse.urlencode({
   "area": "北京"}).encode("utf-8")
req = urllib.request.Request(url, data=data, method="POST")
req.add_header("content-type", "application/x-www-form-urlencoded")
with urllib.request.urlopen(req, timeout=10) as r:
    print(r.read().decode("utf-8"))

8.2 Java

import java.io.*;
import java.net.*;
import java.net.URLEncoder;

public class AirQualityDemo {
   
    public static void main(String[] args) throws Exception {
   
        String url = "https://route.showapi.com/104-42?appKey=YOUR_APPKEY";
        String body = "area=" + URLEncoder.encode("北京", "UTF-8");
        HttpURLConnection conn = (HttpURLConnection) new URL(url).openConnection();
        conn.setRequestMethod("POST");
        conn.setDoOutput(true);
        conn.setRequestProperty("content-type", "application/x-www-form-urlencoded");
        try (OutputStream os = conn.getOutputStream()) {
    os.write(body.getBytes("UTF-8")); }
        try (BufferedReader br = new BufferedReader(new InputStreamReader(conn.getInputStream(), "UTF-8"))) {
   
            StringBuilder sb = new StringBuilder();
            String line;
            while ((line = br.readLine()) != null) sb.append(line);
            System.out.println(sb);
        }
    }
}

8.3 PHP

<?php
$url = "https://route.showapi.com/104-42?appKey=YOUR_APPKEY";
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query(["area" => "北京"]));
curl_setopt($ch, CURLOPT_HTTPHEADER, ["content-type: application/x-www-form-urlencoded"]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$resp = curl_exec($ch);
curl_close($ch);
echo $resp;

8.4 JavaScript（Node.js）

const https = require("https");
const querystring = require("querystring");

const data = querystring.stringify({
    area: "北京" });
const url = "https://route.showapi.com/104-42?appKey=YOUR_APPKEY";
const req = https.request(
  url,
  {
   
    method: "POST",
    headers: {
   
      "content-type": "application/x-www-form-urlencoded",
      "content-length": Buffer.byteLength(data),
    },
  },
  (res) => {
   
    let body = "";
    res.on("data", (c) => (body += c));
    res.on("end", () => console.log(body));
  }
);
req.write(data);
req.end();

8.5 完整返回字段样例

接入点 104-41（全国城市空气质量排行榜）返回字段

接入点 104-42（按城市查询）返回字段

返回 JSON 样例（104-42）

{
   
  "showapi_res_code": 0,
  "showapi_res_error": "",
  "showapi_res_id": "ce135f6739294c63be0c021b76b6fbff",
  "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
  }
}

九、接口调用限制与服务规范

• 请求方式：POST / GET，表单编码 application/x-www-form-urlencoded。
• 更新频率：数据约每半小时更新（产品简介亦描述小时级粒度）。
• 每日配额 / QPS：以控制台实时配置为准；高并发与批量需求可通过套餐扩容与商务支持申请。对于空气质量批量查询 API 需求，建议通过循环调用或提升套餐档位满足，单账户避免瞬时高频以免触发限流。
• 小地区定位规则：国家仅公布约 370 个主要城市数据，查询小地区时返回其上级主要城市的空气质量（如「双桥镇」返回「承德」）。
• 计费扣减规则：在阿里云云市场调用时，仅当 HTTP 响应状态码为 200 时扣减次数，非 200 不扣费。
• 合规要求：请按服务范围合规使用数据，不得用于非法用途；接口调用需遵守平台频率与配额限制，避免高频滥用导致限流。
• 密钥安全：AppKey / APPCODE 须妥善保管，避免泄露；建议服务端调用，不在前端明文暴露密钥。

十、SLA 服务指标

下列为参考性服务指标，具体以控制台实时配置与订购套餐为准。作为稳定空气质量服务接口，本服务在典型网络环境下可提供秒级响应，满足大多数业务对时效的要求。

十一、计费套餐 & 免费试用政策

该服务在阿里云云市场提供免费试用与多档阶梯套餐，按调用次数计费，成本可预期。作为免费空气质量接口试用入口，新用户可先以 20 次免费配额完成接入验证，再按需升级付费套餐：

• 组合套餐：提供套餐价（如 ￥4 起）的多版本组合，满足不同规模需求。
• 扣费规则：仅 HTTP 200 响应扣减次数，非 200 不扣费。
• 发票：金额满 50 元可申请电子普通发票；满 200 元可申请电子专用发票。
• 配额提醒：资源包余量低于阈值或临近到期时会发送通知，便于及时续订。

查看商品详情与最新套餐，请访问阿里云云市场：https://market.aliyun.com/detail/cmapi010843?spm=5176.shop.result.90.26f753d14WrY2t&innerSource=search#sku=yuncode4843000010

十二、接口能力边界 & 服务范围说明

• 支持：全国最多 367 个主要城市的空气质量查询；排行榜与按城市查询；AQI/PM2.5/PM10/SO₂/NO₂/O₃/CO 及类别、首要污染物返回；MCP 与 OpenAPI 接入。
• 不支持：未公布监测点的极小地区不单独返回自身数据，统一回溯上级主要城市；不提供历史逐年归档（以页面更新频率为准）；不提供逐分钟级实时刷新。
• 边界说明：空气质量数据来源于公开监测体系，更新存在约半小时延迟；小地区查询以所属主要城市数据为准。
• 免责声明：接口数据仅供参考，不构成任何健康、出行或投资决策依据；因数据延迟、缺失导致的业务影响，服务方不承担责任。

十三、竞品差异化竞争优势

十四、行业落地应用案例

• 环境监测 / 政务：环保大屏接入排行榜（104-41），实时展示城市空气质量名次。某市级平台接入后，运营人员无需手工采集即可每日更新榜单，人工成本下降约 70%。
• 智能硬件：空气净化器厂商调用按城市查询（104-42）获取 PM2.5，AQI 超阈值自动提升风速，设备联动准确率提升。
• 交通出行 / 地图：出行 APP 在目的地详情页嵌入 AQI 与首要污染物，用户出行前健康提示覆盖率提升。
• 互联网资讯：天气类站点嵌入空气质量模块，内容页停留时长与回访率提升。
• 企业 ERP / 园区：工厂将空气质量纳入职业卫生看板，污染天气自动提醒户外作业班组。
• 小程序 / APP：创业团队基于小程序空气质量接口一周内上线查询功能，验证免费试用配额可覆盖初期验证。

十五、错误码说明 & 常见问题排查指南

十六、独立 FAQ 常见问答专区

Q：这个空气质量接口能查哪些数据？
A：可查询全国最多 367 个城市的 AQI、PM2.5、PM10、SO₂、NO₂、O₃、CO 浓度，以及空气质量类别与首要污染物，并提供城市空气质量排行榜。

Q：有免费试用吗？额度多少？
A：提供免费试用，套餐配额为 20 次；另有 0.1 元/30 次等低价测试套餐，便于接入验证。详见阿里云云市场商品页：https://market.aliyun.com/detail/cmapi010843?spm=5176.shop.result.90.26f753d14WrY2t&innerSource=search#sku=yuncode4843000010

Q：响应速度和稳定性如何？
A：典型响应为秒级，数据约每半小时更新；具体可用率与并发以控制台实时配置为准。

Q：支持批量或高并发调用吗？
A：支持按量套餐扩容与商务定制，高并发场景可联系技术支持申请专属配置。

Q：数据多久刷新一次？
A：约每半小时更新一次；产品简介亦描述为小时级粒度。

Q：查询小城市没数据怎么办？
A：国家仅公布约 370 个主要城市数据，小地区会返回其上级主要城市的空气质量，可改用上级城市名查询。

Q：支持私有化部署或定制吗？
A：标准以云市场 API 形式提供；私有化与大规模定制可通过商务对接评估。

Q：能在 ERP / 小程序 / APP 里用吗？
A：可以。接口基于标准 HTTP/JSON，提供多语言示例，并支持 MCP 与 OpenAPI，便于 ERP、小程序、APP 集成。

Q：怎么计费？有隐藏费用吗？
A：按调用次数阶梯计费，仅 HTTP 200 响应扣减次数，非 200 不扣费；无隐藏费用，价格以商品页套餐为准。

Q：接入需要什么资质？如何上手？
A：在阿里云云市场开通并获取 AppKey/APPCODE 即可调用；提供在线调试、多语言示例与 OpenAPI 文档，上手成本低。

十七、内容小结

全国城市空气质量查询 API 提供覆盖全国最多 367 个城市、约每半小时更新的标准化空气质量数据接口，返回 AQI、六项污染物浓度、空气质量类别与首要污染物，并支持排行榜与按城市查询两种接入点。接口基于标准 HTTP/JSON，提供 Python/Java/PHP/JS 示例及 MCP、OpenAPI 接入能力，适用于环境监测、智能硬件、交通出行、互联网资讯、企业 ERP、小程序/APP 等场景。计费采用免费试用 + 阶梯套餐，仅 200 响应扣费，成本透明。

接入时需注意小地区回溯上级城市的定位规则、配额与限流限制，并合规使用数据。建议优先在服务控制台完成在线调试与多语言示例验证，再纳入生产集成。

了解套餐与最新价格，请访问阿里云云市场商品页：https://market.aliyun.com/detail/cmapi010843?spm=5176.shop.result.90.26f753d14WrY2t&innerSource=search#sku=yuncode4843000010