天气数据 API 接入实践：参数设计、返回解析与工程化注意事项

1. 背景与适用场景

天气预报类数据是生活服务、出行、农业、IoT 等应用中常见的基础数据需求。通过接入标准化的天气数据接口，可以在应用内展示实时天气、未来数天预报、生活指数等信息，而无需自行维护气象站点或解析原始气象文件。

典型的接入方包括：本地生活服务平台、出行导航应用、智能硬件 App、能源与农业管理系统等。需要注意的是，天气数据属于对外采购的第三方数据，接入时应遵循最小必要原则，仅请求业务必需字段并做好缓存，避免频繁调用带来的成本与稳定性压力。

2. 接口概览

本文以阿里云市场「天气预报查询」接口中的 /area-to-weather-date 路径为例，介绍如何按地区编码或地区名称查询指定日期的天气数据。

• 调用方式：HTTP GET
• 返回格式：JSON
• 鉴权方式：Authorization: APPCODE YOUR_APPCODE（同时支持 AppKey + AppSecret 签名，本文示例统一使用 APPCODE）
• 调用地址：/area-to-weather-date（完整调用地址见控制台）

该接口支持通过地区编码 areaCode 或地区名称 area 查询，两者至少传入一个；同时可传入 date 指定查询日期、need3HourForcast 控制是否返回逐小时预报。接口返回内容包含白天/夜间天气、气温、风向以及生活指数等字段。

3. 请求参数

请求参数通过 Query 传递，具体说明如下：

调用时建议优先使用 areaCode，因为地区名称存在同名或简称歧义的风险。date 用于查询指定日期，留空时由服务端按默认规则返回。

4. 返回结构

接口返回为 JSON 结构，顶层字段如下：

showapi_res_body 中的关键字段示例：

完整成功响应示例（已脱敏）：

{
   
  "showapi_res_code": 0,
  "showapi_res_error": "",
  "showapi_res_body": {
   
    "f6": {
   
      "day_weather": "小雨",
      "night_weather": "小雨",
      "night_weather_code": "07",
      "index": {
   
        "clothes": {
   
          "title": "较舒适",
          "desc": "建议穿薄外套或牛仔裤等服装。"
        },
        "uv": {
   
          "title": "最弱",
          "desc": "辐射弱，涂擦 SPF8-12 防晒护肤品。"
        },
        "wash_car": {
   
          "title": "不宜",
          "desc": "有雨，雨水和泥水会弄脏爱车。"
        }
      }
    }
  }
}

实际返回中 index 还会包含约会、晾晒、钓鱼、化妆、心情、旅游、划船、中暑、感冒、逛街、晨练、太阳镜、空气质量、空调控制、美发、过敏、啤酒、夜生活等指数字段，具体以接口实时返回为准。

5. 错误码与排查

接口的错误信息分为两层：HTTP 层状态码与业务层 ret_code。

常见的调用失败原因包括：

• 鉴权头 Authorization 缺失或 APPCODE 错误。
• areaCode 与 area 同时为空，导致无法定位地区。
• date 格式非法或超出接口支持的时间范围。
• 请求 URL 路径错误。

失败响应示例：

{
   
  "showapi_res_code": 0,
  "showapi_res_error": "",
  "showapi_res_body": {
   
    "ret_code": -1,
    "remark": "参数错误"
  }
}

6. 频控与合规

• 调用次数：按实际调用次数扣减额度，仅当 HTTP 状态码为 200 且业务返回成功时扣减；HTTP 555 或业务失败时不扣减。具体扣减规则以控制台公示为准。
• QPS 与配额：每个账号的 QPS 上限、每日调用配额以控制台实时配置为准。上线前建议在测试环境压测，确认不会触发限流。
• 数据合规：天气数据虽不属于敏感个人信息，但仍建议遵循最小必要原则，只请求业务需要的字段；在日志中避免长期存储原始请求与响应全文；如需在前端展示，尽量通过后端服务转发，避免暴露密钥。

7. 多语言接入示例

以下示例统一使用 APPCODE 鉴权，请求路径中的 YOUR_ENDPOINT 请替换为控制台中的完整调用地址。

curl

curl -i -X GET \
  "YOUR_ENDPOINT/area-to-weather-date?areaCode=530700&date=20200319&need3HourForcast=1" \
  -H "Authorization: APPCODE YOUR_APPCODE"

Python

import requests

ENDPOINT = "YOUR_ENDPOINT"  # 完整调用地址见控制台
APPCODE = "YOUR_APPCODE"

params = {
   
    "areaCode": "530700",
    "date": "20200319",
    "need3HourForcast": "1"
}

resp = requests.get(
    f"{ENDPOINT}/area-to-weather-date",
    params=params,
    headers={
   "Authorization": f"APPCODE {APPCODE}"},
    timeout=10
)
data = resp.json()
print(data)

Java

import okhttp3.HttpUrl;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.Response;

public class WeatherDemo {
   
    public static void main(String[] args) throws Exception {
   
        OkHttpClient client = new OkHttpClient();
        HttpUrl url = HttpUrl.parse("YOUR_ENDPOINT/area-to-weather-date")
            .newBuilder()
            .addQueryParameter("areaCode", "530700")
            .addQueryParameter("date", "20200319")
            .addQueryParameter("need3HourForcast", "1")
            .build();
        Request request = new Request.Builder()
            .url(url)
            .addHeader("Authorization", "APPCODE YOUR_APPCODE")
            .build();
        try (Response response = client.newCall(request).execute()) {
   
            System.out.println(response.body().string());
        }
    }
}

Node.js

const axios = require('axios');

const ENDPOINT = 'YOUR_ENDPOINT';
const APPCODE = 'YOUR_APPCODE';

axios.get(`${
     ENDPOINT}/area-to-weather-date`, {
   
  params: {
   
    areaCode: '530700',
    date: '20200319',
    need3HourForcast: '1'
  },
  headers: {
   
    Authorization: `APPCODE ${
     APPCODE}`
  },
  timeout: 10000
}).then(res => {
   
  console.log(res.data);
}).catch(err => {
   
  console.error(err.response ? err.response.data : err.message);
});

PHP

<?php
$endpoint = 'YOUR_ENDPOINT';
$appcode = 'YOUR_APPCODE';
$url = $endpoint . '/area-to-weather-date?areaCode=530700&date=20200319&need3HourForcast=1';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: APPCODE ' . $appcode
]);
$output = curl_exec($ch);
curl_close($ch);
echo $output;

8. 接入工程实践

• 参数前置校验：调用前校验 areaCode 或 area 至少存在一个；date 符合 yyyyMMdd 格式。
• 失败重试：仅对幂等且非鉴权错误的请求重试；遇到 555 时先排查参数，不要盲目重试。
• 缓存策略：天气数据更新频率较低，预报类数据可设置 1~4 小时 TTL，历史数据可设置 24 小时 TTL，减少重复调用。
• 超时与连接池：设置合理超时（建议 5~10 秒），生产环境使用连接池避免每次新建连接。
• 密钥安全：APPCODE 应存储在服务端环境变量或密钥管理系统中，禁止硬编码在前端代码或开源仓库。

9. 技术 FAQ

Q：areaCode 和 area 有什么区别？
A：areaCode 是地区编码，稳定性更高；area 是地区名称，可能存在同名或简称歧义。两者至少传一个，同时传入时优先使用 areaCode。

Q：need3HourForcast 传什么值？
A：传 1 表示需要 3 小时级别的预报数据；不传或传其他值时由接口默认规则返回。

Q：返回的 showapi_res_code 和 ret_code 是什么关系？
A：showapi_res_code 是阿里云 API 网关层状态码，0 表示请求已到达服务端；ret_code 是业务层状态码，0 表示业务处理成功，-1 表示业务失败。

Q：调用失败会扣费吗？
A：根据接口规则，HTTP 200 + ret_code=0 扣减调用次数；HTTP 555 或 ret_code=-1 不扣减。具体以控制台实时规则为准。

10. 小结

本文以「按地区查询指定日期天气」接口为例，梳理了其请求参数、返回结构、错误码含义、多语言调用方式以及工程化接入中的缓存与密钥安全注意事项。实际接入时，建议先在控制台确认完整调用地址、APPCODE 以及配额限制，再逐步集成到业务系统中。