空气质量 API：位置优先级、AQI 标准与数据新鲜度

GuGuData 空气质量 API 使用 GET 查询已覆盖位置的 AQI、污染物和监测信息。支持 location 或兼容 city 参数，至少提供一项，同时提供时 location 优先。Data 是结果数组；AQI、污染物浓度和数据新鲜度应一起读取，不能只根据一个数值判断口径。

接口与输入

项目	说明
请求方法	GET
接口地址	https://api.gugudata.com/Weather/AirQuality
返回格式	JSON，UTF-8
鉴权	对应产品有效 AppKey；示例通过 Header 提供

参数名	参数类型	是否必须	默认值	备注
appkey	string	是	无	接口调用凭证，请在咕咕数据开发者中心获取
location	string	否	无；至少传一项	推荐参数。支持城市名称、LocationID 或 经度,纬度；与 city 同时传递时优先生效
city	string	否	无；至少传一项	城市名称；未传 location 时生效。location 与 city 至少传递一个。
lang	string	否	zh	返回语言，支持 zh 或 en，默认 zh

参数名与大小写按当前契约传递，鉴权凭据只需使用一种受支持的方式。公开文章不放真实 AppKey。

请求示例

以下是集成示例，YOUR_APPKEY 为占位符，未使用真实凭据执行。正式调用需要对应产品权益。查询参数由 --data-urlencode 分别编码，避免中文或特殊字符破坏 URL。

curl --get 'https://api.gugudata.com/Weather/AirQuality' \
  --header 'X-GUGUDATA-APPKEY: YOUR_APPKEY' \
  --data-urlencode 'location=北京' \
  --data-urlencode 'lang=zh'

返回字段

参数名	参数类型	备注
Data	array(object)	结果对象数组，不能当作单个对象读取。
DataStatus.RequestParameter	string	本次实际业务请求参数，不包含鉴权凭据；Demo 展示对应样例输入。
DataStatus.StatusCode	integer	业务状态码，100 表示成功
DataStatus.StatusDescription	string	业务状态说明
DataStatus.ResponseDateTime	string	接口响应生成时间，不代表来源资料更新时间。
DataStatus.DataTotalCount	integer	返回结果数量。
Data[].Province	string / null	一级行政区名称
Data[].City	string	匹配到的位置名称
Data[].LocationId	string	位置 LocationID
Data[].Latitude	string	位置纬度
Data[].Longitude	string	位置经度
Data[].Country	string / null	国家或地区
Data[].AQI	string	空气质量指数数值
Data[].AQIStandard	string / null	本条结果采用的 AQI 标准代码，例如 cn-mee 或 us-epa
Data[].AQIDisplay	string / null	适合直接展示的 AQI 文本
Data[].AQILevel	string / null	AQI 等级
Data[].Quality	string	空气质量等级描述
Data[].AQIColor	object / null	AQI 等级对应的 RGBA 颜色
Data[].AQIColor.Red	integer / null	红色通道，范围 0 至 255
Data[].AQIColor.Green	integer / null	绿色通道，范围 0 至 255
Data[].AQIColor.Blue	integer / null	蓝色通道，范围 0 至 255
Data[].AQIColor.Alpha	number / null	透明度
Data[].PM25	string / null	PM2.5 浓度，单位见 Pollutants.Unit
Data[].PrimaryPollutant	string / null	首要污染物显示名称
Data[].PrimaryPollutantCode	string / null	首要污染物代码
Data[].PrimaryPollutantName	string / null	首要污染物名称
Data[].PrimaryPollutantFullName	string / null	首要污染物完整名称
Data[].HealthEffect	string / null	当前空气质量可能造成的健康影响
Data[].GeneralPopulationAdvice	string / null	一般人群健康建议
Data[].SensitivePopulationAdvice	string / null	敏感人群健康建议
Data[].Pollutants	array	主要污染物浓度及分项 AQI
Data[].Pollutants[].Code	string	污染物代码
Data[].Pollutants[].Name	string	污染物名称
Data[].Pollutants[].FullName	string / null	污染物完整名称
Data[].Pollutants[].Concentration	string / null	污染物浓度
Data[].Pollutants[].Unit	string / null	污染物浓度单位
Data[].Pollutants[].AQI	string / null	污染物分项 AQI
Data[].Pollutants[].AQIDisplay	string / null	污染物分项 AQI 展示文本
Data[].Stations	array	参与当前结果的监测站列表
Data[].Stations[].Id	string / null	监测站标识
Data[].Stations[].Name	string / null	监测站名称
Data[].RetrievedAt	string	本条空气质量数据的获取时间，ISO 8601 格式
Data[].DataStatus	string	数据时效状态。

公开样例与结果核对

2026 年 11 月 7 日回读了当前公开样例。公开 Demo 的输入为 location=北京、lang=zh，与上方请求一致。以下仅保留第一个结果的部分字段及第一种污染物，其余字段已省略。

{
  "DataStatus": {
    "StatusCode": 100,
    "RequestParameter": "location=北京&lang=zh",
    "DataTotalCount": 1
  },
  "Data": [
    {
      "City": "北京",
      "LocationId": "101010100",
      "AQI": "40",
      "AQIStandard": "cn-mee",
      "Quality": "优",
      "PM25": "18",
      "RetrievedAt": "2026-11-07T01:57:51Z",
      "DataStatus": "fresh",
      "Pollutants": [
        {
          "Code": "pm2p5",
          "Name": "PM 2.5",
          "FullName": "颗粒物（粒径小于等于2.5µm）",
          "Concentration": "18",
          "Unit": "μg/m³",
          "AQI": "26",
          "AQIDisplay": "26"
        }
      ]
    }
  ]
}

公开样例证明采样时的返回结构，不代表带占位符的生产请求已经执行，也不用于推断全部数据覆盖或固定响应性能。响应时间和样例日期各有含义，应与 RequestParameter 一起核对。

字段口径与适用边界

location 支持城市名、LocationID 或“经度,纬度”；经纬度顺序不能颠倒。lang 支持 zh 和 en。AQI 数值与 PM2.5 浓度含义不同，PM25 的浓度单位应与 Pollutants.Unit 核对，不能把 mg/m³ 和 μg/m³ 混用。不同位置可能采用 cn-mee 或 us-epa 等 AQIStandard，不应直接跨标准套用等级阈值；原始封面中的等级示意仅作插图，不作为当前返回标准的阈值表。顶层 DataStatus 是接口业务状态，Data[].DataStatus 则为 fresh 或 stale 的资料时效状态。stale 表示数据服务异常时的最近成功资料；应同时展示 RetrievedAt，不能改标为实时。污染物、建议和监测站资料受覆盖影响，null、空串和空数组应保留含义。

错误与使用建议

先检查 HTTP 状态，再检查 DataStatus.StatusCode，100 表示业务成功。成功后仍应检查实际 Data 与返回计数；参数、鉴权、订单、额度、限流和依赖错误需要分别处理，不能把服务失败伪装成空数据。错误码和频率限制以当前官方文档与订单信息为准。

适合环境信息看板和出行资料展示。按当前返回的标准、质量文字和数据时间展示，不自行补造缺失监测值，也不据单个示例宣称覆盖所有城市。

参考文档

• 完整接口文档
• 公开 OpenAPI

本文由 GuGuData 产品方整理，接口契约核对日期为 2026 年 11 月 7 日。