天气实况与多日预报查询接口接入指南｜输入地名或地区编码，获取温度湿度风力与空气质量指数

一、技术简介

天气数据查询接口提供天气实况与多日预报的聚合查询能力。调用方传入地名或地区编码，即可返回该区域的实时天气、未来多日天气预报、生活指数与恶劣天气预警等结构化数据。返回内容覆盖温度、湿度、风向风力、紫外线、空气质量指数（AQI）及 PM2.5 等明细字段，适用于需要稳定获取气象数据的业务系统。

接口采用 RESTful 风格，支持 POST 与 GET 两种请求方式，返回格式为 JSON。业务数据统一封装在响应体的内层对象中，外层为系统级状态字段。

能力概览图

二、能力概览

项目	说明
调用方法	HTTP POST / GET
返回格式	JSON
入参	地名 `area` 或地区编码 `areaCode`（二选一必填）
鉴权方式	`Authorization: APPCODE <appcode>`（Header）
核心返回	实时天气 `now`、当日预报 `f1`、未来六日预报 `f2`–`f7`、地区信息 `cityInfo`、预警列表 `alarmList`
典型用途	实况展示、多日出行规划、空气质量监测、预警提醒

可选开关参数控制返回的数据维度：是否返回后四日数据、生活指数、逐 3/6/8 小时预报、预警信息、逐小时累积数组。按需开启可减少响应体积。

三、适用场景

出行与旅游平台：展示目的地当日及未来几日天气，辅助用户决策行程与装备。
物流与运单调度：结合大风、暴雨等预警字段，对高风险路线做提前调度与提示。
健康与穿戴类应用：读取 AQI、PM2.5、紫外线、感冒指数，向敏感人群推送防护建议。
农业与设施监控：依据降水概率、温湿度趋势安排灌溉与户外作业窗口。
智能家居与气象看板：定时拉取实况温度、湿度，驱动联动策略或可视化大屏。

适用场景示意图

四、接入流程

开通与获取凭证：在控制台开通对应服务，取得调用凭证 appcode，用于后续请求鉴权。
确定查询区域：准备目标区域的地名（如「丽江」）或地区编码（如 530700）。两者至少提供一个，同时提供时以地区编码为准。
构造请求：按所需维度设置可选开关参数，将鉴权信息放入请求头。
解析响应：读取外层状态字段确认成功，再从内层业务对象提取 now、f1、cityInfo 等所需数据。
落库与缓存：对变化频率较低的预报数据做本地缓存，降低重复调用。

接入流程图

五、调用示例与返回结构

5.1 请求参数

参数位置	参数名	类型	必填	说明
Query / Form	`area`	String	否	查询地区名称，与 `areaCode` 至少填一个；两者都填时取 `areaCode`
Query / Form	`areaCode`	String	否	地区编码，如 `530700`
Query / Form	`needMoreDay`	String	否	是否返回 7 天中后 4 天数据，`1` 返回，`0` 不返回
Query / Form	`needIndex`	String	否	是否返回生活指数（穿衣、紫外线等），`1` 返回，`0` 不返回
Query / Form	`need3HourForcast`	String	否	是否返回当日逐 3/6/8 小时预报列表，`1` 需要，`0` 不需要
Query / Form	`needAlarm`	String	否	是否返回天气预警，`1` 需要，`0` 不需要
Query / Form	`needHourData`	String	否	是否返回逐小时累积数组，`1` 需要，`0` 不需要
Header	`Authorization`	String	是	鉴权头，格式 `APPCODE <appcode>`

5.2 完整返回结构

{
   
  "showapi_res_code": 0,
  "showapi_res_error": "",
  "showapi_res_body": {
   
    "time": "201203061100",
    "ret_code": 0,
    "cityInfo": {
   
      "c1": "110114",
      "c2": "beijing",
      "c3": "北京",
      "c7": "北京",
      "c8": "china",
      "c9": "中国",
      "c10": "1",
      "c11": "010",
      "c12": "100000",
      "longitude": "116.391",
      "latitude": "39.904",
      "c0": "110114"
    },
    "now": {
   
      "aqi": "65",
      "sd": "56%",
      "temperature": "26",
      "temperature_time": "15:00",
      "weather": "阴",
      "weather_pic": "https://example.com/icon/day/02.png",
      "wind_direction": "南风",
      "wind_power": "1级",
      "feels_like": "26",
      "rain": "0.0",
      "aqiDetail": {
   
        "aqi": "38",
        "area": "昆明",
        "co": "0.713",
        "no2": "12",
        "o3": "104",
        "pm10": "37",
        "pm2_5": "19",
        "primary_pollutant": "颗粒物(PM2.5)",
        "quality": "优",
        "so2": "13"
      }
    },
    "f1": {
   
      "day_weather": "多云",
      "night_weather": "暴雨",
      "day_air_temperature": "26",
      "night_air_temperature": "12",
      "day_wind_direction": "东北风",
      "night_wind_direction": "西北风",
      "day_wind_power": "3-4级10~17m/h",
      "night_wind_power": "微风<10m/h",
      "sun_begin_end": "06:44|18:21",
      "day": "20150627",
      "weekday": 6,
      "day_weather_code": "01",
      "night_weather_code": "02",
      "air_press": "1005",
      "jiangshui": "80%",
      "ziwaixian": "很强",
      "index": {
   
        "clothes": "舒适",
        "cold": "易发",
        "comfort": "舒适",
        "sports": "较适宜",
        "travel": "适宜",
        "uv": "很强",
        "wash_car": "适宜"
      }
    },
    "f2": {
    "day_weather": "晴", "day_air_temperature": "27" },
    "alarmList": [
      {
   
        "signalLevel": "橙色",
        "signalType": "暴雨",
        "issueContent": "预计未来 3 小时仍有强降水",
        "issueTime": "20150627",
        "province": "北京",
        "city": "北京"
      }
    ]
  }
}

关键字段含义

字段路径	类型	含义
`showapi_res_body.ret_code`	Number	业务状态码，`0` 表示成功
`cityInfo.c0`	String	地区编码
`cityInfo.longitude` / `latitude`	String	经度 / 纬度
`now.temperature`	String	当前气温（摄氏度）
`now.sd`	String	空气湿度百分比
`now.aqi`	String	空气质量指数，数值越小越好
`now.aqiDetail.pm2_5`	String	PM2.5 一小时平均浓度（μg/m³）
`now.aqiDetail.quality`	String	空气质量类别（优 / 良 / 轻度污染等）
`now.feels_like`	String	体感温度
`f1.day_weather` / `night_weather`	String	当日昼 / 夜间天气
`f1.day_air_temperature` / `night_air_temperature`	String	昼 / 夜间气温
`f1.index`	Object	生活指数集合（穿衣、感冒、紫外线等）
`f2`–`f7`	Object	当日之后第 1 至第 6 日的天气预报
`alarmList`	Array	恶劣天气预警列表，含等级、类型、内容、时间

返回结构示意图

5.3 多语言调用示例

以下示例均使用 Header 鉴权 Authorization: APPCODE <appcode>，调用地址以控制台显示为准。

Python

import requests

url = "调用地址"  # 以控制台显示为准
headers = {
   "Authorization": "APPCODE <appcode>"}
params = {
   
    "area": "丽江",
    "needIndex": "1",
    "needAlarm": "1"
}
resp = requests.get(url, params=params, headers=headers, timeout=10)
data = resp.json()
body = data.get("showapi_res_body", {
   })
if body.get("ret_code") == 0:
    now = body.get("now", {
   })
    print("气温:", now.get("temperature"), "湿度:", now.get("sd"), "AQI:", now.get("aqi"))

Java

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;

public class WeatherDemo {
   
    public static void main(String[] args) throws Exception {
   
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create("调用地址?area=丽江&needIndex=1&needAlarm=1"))
                .header("Authorization", "APPCODE <appcode>")
                .build();
        HttpResponse<String> response = client.send(request,
                HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

PHP

<?php
$url = "调用地址?area=" . urlencode("丽江") . "&needIndex=1&needAlarm=1";
$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["Authorization: APPCODE <appcode>"],
    CURLOPT_TIMEOUT => 10,
]);
$body = curl_exec($ch);
curl_close($ch);
$data = json_decode($body, true);
echo $data["showapi_res_body"]["now"]["temperature"] ?? "";

Node.js

const https = require("https");
const url = "调用地址?area=" + encodeURIComponent("丽江") + "&needIndex=1&needAlarm=1";
const req = https.get(url, {
    headers: {
    Authorization: "APPCODE <appcode>" } }, (res) => {
   
  let chunks = "";
  res.on("data", (c) => (chunks += c));
  res.on("end", () => {
   
    const data = JSON.parse(chunks);
    console.log(data.showapi_res_body.now.temperature);
  });
});
req.on("error", (e) => console.error(e));

六、在线调试实录

在控制台调试模块中填写参数时，建议遵循以下顺序：

先在「地名」输入框填入目标城市（如「丽江」），或直接填入地区编码。系统对同名地区默认取数据库排序的第一条，若结果不符应改用编码精确指定。
按需勾选 needIndex、needAlarm 等开关。调试阶段建议全部开启，确认字段含义后再在生产环境裁剪。
发送请求后，先检查外层 showapi_res_code 与内层 ret_code 是否均为 0，再解析业务字段。
观察 now 与 f1 的时间戳，确认返回的是当前实况与当日预报，避免把缓存旧数据误认为实时值。

在线调试示意图

七、调用限制与规范

必填约束：area 与 areaCode 至少提供一个；同时提供时以 areaCode 为准。
更新频率：实时天气与恶劣天气预警约 30 分钟更新一次；f1–f7 预报数据每日更新 3 次（约 7:30、12:00、18:00），反映从当日起往后 7 天。
逐小时数组：needHourData 开启时返回当日每半小时累积数组，最大长度 48，每日 0 点重置。
频率控制：对高频调用的业务建议设置客户端限流与重试退避，避免短时间突发请求。
错误处理：对网络超时与非 0 状态码应做统一异常分支，避免解析失败崩溃。

八、能力边界与免责声明

本接口提供的是公开气象数据的聚合与再加工结果，数据存在更新延迟，不应作为高精度实时决策（如航空、医疗急救）的唯一依据。
返回内容仅供技术集成参考，不构成任何专业气象、健康或安全建议；涉及人身安全的关键场景需结合官方发布渠道交叉核验。
调用方应遵守数据使用协议，不得将接口用于违规用途，并妥善保管 appcode 凭证，防止泄露与盗用。
对返回的个人无关敏感数据不做长期存储；确需落库时应做好访问控制与脱敏。
天气预警信息以当地气象主管机构发布为准，本接口的预警字段仅作辅助提醒。

九、错误码与排查

现象	可能原因	处理建议
外层 `showapi_res_code` 非 0	系统级异常或鉴权失败	核对 `appcode` 与请求头格式，查看 `showapi_res_error`
内层 `ret_code` 非 0	业务参数错误	检查 `area` / `areaCode` 是否合法、是否至少提供一个
返回地区与预期不符	同名地区取首条	改用地区编码 `areaCode` 精确指定
实时字段为空	请求过于频繁或未开启对应开关	确认 `needHourData` 等开关，降低调用频率
响应超时	网络或限流	增加超时与重试退避，检查客户端限流配置

错误码排查示意图

十、技术 FAQ

Q1：地名和地区编码应该怎么选？
两者至少提供一个。同名城市较多时建议直接使用地区编码，可避免系统默认取首条导致的偏差。两者同时传入时，接口以地区编码为准。

Q2：预报数据多久更新一次，能当实时用吗？
实时天气与预警约 30 分钟刷新；多日预报每日更新 3 次。接口数据存在更新延迟，不适合作为对时效性要求极高场景的唯一来源。

Q3：生活指数和预警默认返回吗？
不默认返回，需通过 needIndex、needAlarm 等开关显式开启。生产环境可按页面实际需要裁剪，减小响应体积。

Q4：逐小时数据为什么长度是 48 且每日重置？
系统每半小时刷新一次实时状态，逐小时数组最大长度为 48，每日 0 点初始化。开启 needHourData 才能获取。

Q5：返回结构里为什么有多层封装？
外层为系统级状态字段，业务数据统一放在内层对象中。解析时先判断外层状态，再读取内层 ret_code 与具体字段。

十一、内容小结

天气数据查询接口以「地名或地区编码」为入参，聚合返回实时天气、多日预报、生活指数与预警等结构化数据，覆盖温度、湿度、风力、空气质量等常用维度。接入要点：使用 Header 鉴权、按需开启数据维度开关、先校验状态字段再解析业务对象、对低频变化的预报做本地缓存。工程上建议补充限流、重试退避与异常分支，并将接口数据作为参考而非唯一决策依据。

天气实况与多日预报查询接口接入指南｜输入地名或地区编码，获取温度湿度风力与空气质量指数

天气实况与多日预报查询接口接入指南｜输入地名或地区编码，获取温度湿度风力与空气质量指数

一、技术简介

二、能力概览

三、适用场景

四、接入流程

五、调用示例与返回结构

5.1 请求参数

5.2 完整返回结构

关键字段含义

5.3 多语言调用示例

六、在线调试实录

七、调用限制与规范

八、能力边界与免责声明

九、错误码与排查

十、技术 FAQ

十一、内容小结

云市场头条

热门文章

最新文章

相关电子书

探索云世界

热门

云计算

大数据

云原生

人工智能

数据库

开发与运维

活动广场

任务中心

训练营

直播

乘风者计划

下载

镜像站

技术资料

天气实况与多日预报查询接口接入指南｜输入地名或地区编码，获取温度湿度风力与空气质量指数

天气实况与多日预报查询接口接入指南｜输入地名或地区编码，获取温度湿度风力与空气质量指数

一、技术简介

二、能力概览

三、适用场景

四、接入流程

五、调用示例与返回结构

5.1 请求参数

5.2 完整返回结构

关键字段含义

5.3 多语言调用示例

六、在线调试实录

七、调用限制与规范

八、能力边界与免责声明

九、错误码与排查

十、技术 FAQ

十一、内容小结

云市场头条

热门文章

最新文章

相关电子书