历史天气查询接口说明：参数设计、返回字段与多语言调用示例

一、接口简介

历史天气查询接口提供按地区查询历史气象数据的能力，支持通过地名、地区代码、经纬度、IP 地址、景点名称、区号邮编等多种维度定位目标区域。返回数据涵盖指定时间段内的每日天气记录，包括最高/最低气温、天气状况、风向风力等要素，部分城市还支持空气质量指数（AQI）返回。数据最早可追溯至 2011 年 1 月，覆盖全国 3000 余个区县及以上城市，更新周期约 30 分钟，适用于能源调度、农业管理、旅游规划、智能硬件、交通出行等多个业务场景。

二、核心能力

三、适用场景

• 能源与电力：历史气温数据辅助预测用电负荷、制定供暖/制冷调度方案
• 农业管理：结合历史气象数据复盘作物生长周期、评估灾害风险
• 旅游与出行：为行程规划提供目的地历史气候参考
• 智能硬件：智能家居设备根据历史温度曲线优化空调/新风策略
• 交通物流：极端天气复盘辅助运力调度与路径规划
• 数据分析：作为数据源接入报表系统，支撑趋势分析与时序可视化

四、功能特点

五、操作流程

5.1 接入准备

1. 在阿里云云市场开通商品（cmapi010812），获取 AppCode
2. 将 AppCode 填入请求 Header：Authorization: APPCODE <your_appcode>
3. 确定查询维度（area 或 areaCode）及时间范围（month 或 startDate/endDate）

5.2 请求参数

注意：area 与 areaCode 至少传入一个；month 与 startDate/endDate 至少传入一个。若两者均传入，以 month 优先。

5.3 调用方式

GET https://ali-weather.showapi.com/weatherhistory
Header: Authorization: APPCODE <your_appcode>
Query: area=北京&month=202406

配图：

六、返回字段说明

6.1 系统级字段

6.2 业务字段（showapi_res_body 内）

配图：

七、在线调试示例

7.1 cURL 示例

curl -X GET "https://ali-weather.showapi.com/weatherhistory?area=北京&month=202406" \
  -H "Authorization: APPCODE your_appcode"

7.2 成功响应示例

{
   
  "showapi_res_code": 0,
  "showapi_res_error": "",
  "showapi_res_id": "a1b2c3d4e5f6",
  "showapi_fee_num": 1,
  "showapi_res_body": {
   
    "area": "北京",
    "areaid": "101010100",
    "list": [
      {
   
        "date": "2024-06-01",
        "max_temp": "31",
        "min_temp": "20",
        "weather": "晴",
        "wind_direction": "南风",
        "wind_power": "3-4 级",
        "aqi": "45",
        "aqi_level": "优",
        "aqi_info": "空气质量令人满意，基本无空气污染"
      },
      {
   
        "date": "2024-06-02",
        "max_temp": "33",
        "min_temp": "22",
        "weather": "多云",
        "wind_direction": "东南风",
        "wind_power": "2-3 级",
        "aqi": "62",
        "aqi_level": "良",
        "aqi_info": "空气质量可接受，某些污染物可能对极少数异常敏感人群健康有较弱影响"
      }
    ]
  }
}

配图：

八、多语言调用示例

8.1 Python

import urllib.request
import urllib.parse
import json

url = "https://ali-weather.showapi.com/weatherhistory"
params = urllib.parse.urlencode({
   
    "area": "北京",
    "month": "202406"
}).encode("utf-8")

req = urllib.request.Request(url, data=params)
req.add_header("Authorization", "APPCODE your_appcode")

with urllib.request.urlopen(req) as resp:
    data = json.loads(resp.read().decode("utf-8"))
    print(json.dumps(data, ensure_ascii=False, indent=2))

8.2 Java

import java.net.HttpURLConnection;
import java.net.URL;
import java.io.BufferedReader;
import java.io.InputStreamReader;

public class WeatherHistory {
   
    public static void main(String[] args) throws Exception {
   
        String urlStr = "https://ali-weather.showapi.com/weatherhistory?area=%E5%8C%97%E4%BA%AC&month=202406";
        URL url = new URL(urlStr);
        HttpURLConnection conn = (HttpURLConnection) url.openConnection();
        conn.setRequestMethod("GET");
        conn.setRequestProperty("Authorization", "APPCODE your_appcode");

        BufferedReader br = new BufferedReader(new InputStreamReader(conn.getInputStream(), "UTF-8"));
        StringBuilder sb = new StringBuilder();
        String line;
        while ((line = br.readLine()) != null) {
   
            sb.append(line);
        }
        br.close();
        System.out.println(sb.toString());
    }
}

8.3 JavaScript (Node.js)

const https = require('https');

const options = {
   
  hostname: 'ali-weather.showapi.com',
  path: '/weatherhistory?area=%E5%8C%97%E4%BA%AC&month=202406',
  method: 'GET',
  headers: {
   
    'Authorization': 'APPCODE your_appcode'
  }
};

const req = https.request(options, (res) => {
   
  let data = '';
  res.on('data', (chunk) => {
    data += chunk; });
  res.on('end', () => {
    console.log(data); });
});

req.on('error', (e) => {
    console.error(e); });
req.end();

8.4 PHP

<?php
$url = 'https://ali-weather.showapi.com/weatherhistory?area=北京&month=202406';
$headers = array(
    'Authorization: APPCODE your_appcode'
);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

配图：

九、调用限制与服务规范

高频注意事项：

• 每次请求最多返回一个月数据（month 模式）或指定区间数据（startDate/endDate 模式）
• 建议对查询结果做本地缓存，避免重复请求同一时间段
• 批量查询多个城市时，建议串行调用并控制间隔，避免触发限流

十、服务指标参考

以上指标为参考值，实际表现可能因网络环境、服务器负载等因素有所波动。

十一、能力边界与服务范围

11.1 支持范围

• 中国境内全部区县及以上城市
• 历史数据：2011 年 1 月至今（部分早期城市数据可能不完整）
• 查询维度：地名（area）/ 地区代码（areaCode）/ 经纬度（location）/ IP 地址（ip）/ 景点名称（scenic）/ 区号邮编（areacode）

11.2 不支持范围

• 境外城市天气数据
• 小时级历史数据（仅支持每日一条记录）
• 未来天气预报（本接口专供历史数据查询）
• 实时天气（请使用独立的实时天气接口）

11.3 免责声明

• 气象数据仅供参考，不作为气象预报或业务决策的唯一依据
• 部分偏远地区或早期数据可能存在缺失或延迟
• 接口返回值以实际调用结果为准，服务商不对第三方使用后果承担责任

十二、错误码说明

配图：

十三、选型思路

针对历史天气数据查询需求，选型时可考虑以下维度：

十四、错误排查清单

十五、常见问题（FAQ）

Q：如何查询某个城市的历史天气？
A：传入 area（地名）或 areaCode（地区代码）加 month（月份）即可，例如 area=北京&month=202406。

Q：历史数据最早可以查到哪一年？
A：最早可追溯至 2011 年 1 月，但早期数据完整性因城市而异。

Q：支持查询具体某几天的数据吗？
A：支持。使用 startDate 和 endDate 指定日期区间，格式为 yyyyMMdd，例如 startDate=20240601&endDate=20240615。

Q：area 和 areaCode 应该用哪个？
A：两者均可，但建议优先使用 areaCode，因为重名城市较多时使用 code 更准确。

Q：返回数据中的 AQI 字段是否所有城市都有？
A：不是。仅部分配备空气质量监测站的城市会返回 AQI 数据，未覆盖城市该字段为空。

Q：接口支持哪些查询维度？
A：支持地名（area）、地区代码（areaCode）、经纬度（location）、IP 地址（ip）、景点名称（scenic）、区号邮编（areacode）六种定位方式。

Q：每天可以调用多少次？
A：每日调用上限以控制台实时配置为准，额度因套餐档位而异。# @marketing-ok

Q：非 200 响应会扣费吗？
A：不会。仅当 HTTP 响应状态码为 200 时扣减调用次数。

十六、内容小结

历史天气查询接口提供稳定、覆盖广的历史气象数据服务能力，支持多种定位维度和灵活的时间范围查询，数据可追溯至 2011 年，覆盖全国 3000+ 区县及以上城市。接口采用 APPCODE 简单鉴权，返回标准 JSON 格式，便于各语言快速接入。

接入时建议注意：优先使用 areaCode 而非 area 避免重名歧义；批量查询多城市时做好结果缓存以控制调用频次；对于无 AQI 数据的城市做好字段容错处理。

本文档仅供参考，接口参数与返回结构以实际调用结果为准。