天气数据查询 API 接入教程：当前 24 小时 / 未来 7 天 15 天 / 历史天气调用实践

一、技术简介

天气数据查询 API 是一类面向开发者的气象数据接口，支持通过多种地理标识方式获取天气信息。接口以地名、经纬度坐标、区号或邮编、IP 地址、景点名称作为查询入参，返回当前 24 小时逐小时天气、未来 7 天与 15 天预报，以及历史天气数据。数据覆盖全国区县级以上行政单元，采用标准 RESTful 形态、JSON 返回，适用于需要在业务系统中集成气象信息的场景。

本文以阿里云云市场提供的天气查询类商品为对象，梳理其接入方式、请求与返回结构、调用约束与工程实践要点，供开发者从零完成对接。

二、能力概览

下表汇总该接口对外提供的能力维度与基本形态：

鉴权方式采用阿里云市场 API 网关标准的 APPCODE 简单认证；返回类型为 JSON；请求方法以商品页给出的接入方式为准。

三、适用场景

天气数据可嵌入多种业务的数据流中，以下为常见的技术接入情境：

天气数据可嵌入多种业务的数据流中，以下为常见的技术接入情境：

• 出行与导航：在路径规划后预取目的地天气，用于提示降水、大风等影响行车的因素。
• 能源与电力：结合温度与光照预报做负荷预测，调度光伏、风电出力。
• 农业生产：依据未来 15 天温度与降水趋势安排灌溉、播种与采收。
• 物流配送：根据逐小时降水概率调整配送窗口，降低异常签收。
• 智能硬件与座舱：依据目的地与当前天气联动空调、除霜、界面主题。
• 旅游与建筑：按景区天气安排客流引导，按风力预警调整高处作业。

上述场景的共同点是：系统已持有某种地理标识（城市名、坐标、IP 等），需要把气象字段作为下游决策的入参。

四、接入流程

接入分为四个步骤，整体链路如接入流程图所示。

4.1 开通与获取凭证

1. 在云市场完成对应商品的开通与资源包订购，进入控制台获取调用地址与 APPCODE。
2. 将 APPCODE 作为请求头 Authorization: APPCODE <appcode> 携带，不在 URL 中拼接密钥。

4.2 组织请求

不同查询维度对应商品页提供的不同接入地址，实际参数名称以控制台/商品页给出的接口定义为准。

4.3 发送与解析

使用任意 HTTP 客户端发起 GET 请求，解析 JSON 中的 result 节点即可得到天气对象。建议对返回做字段存在性校验，避免因单点缺字段导致下游解析异常。

五、调用示例与返回结构

5.1 请求参数设计

以「按 IP 获取天气」为例，请求形如：

GET {网关接入地址}?ip=客户端IP
Header: Authorization: APPCODE <appcode>

下文以结构化 JSON 展示典型返回，字段命名采用中性表达，便于跨语言解析。

5.2 完整返回结构

{
   
  "code": 0,
  "msg": "",
  "result": {
   
    "city": "北京",
    "area": "朝阳区",
    "areaCode": "101010300",
    "now": {
   
      "temperature": 25,
      "weather": "晴",
      "windDirection": "东南风",
      "windPower": "3级",
      "humidity": 40,
      "updateTime": "2026-11-09 13:00"
    },
    "forecast": [
      {
   
        "date": "2026-11-09",
        "week": "周一",
        "dayWeather": "晴",
        "nightWeather": "多云",
        "dayTemp": 26,
        "nightTemp": 15,
        "dayWindDirection": "东南风",
        "dayWindPower": "3级",
        "rainfall": 0,
        "humidity": 42
      }
    ]
  }
}

5.3 字段含义表

5.4 多语言调用示例

Python

import urllib.request
import json

host = "网关接入地址"  # 以商品页/控制台给出的实际地址为准
appcode = "你的APPCODE"

req = urllib.request.Request(f"{host}?ip=8.8.8.8")
req.add_header("Authorization", f"APPCODE {appcode}")

with urllib.request.urlopen(req, timeout=10) as resp:
    data = json.loads(resp.read().decode("utf-8"))

if data.get("code") == 0:
    result = data["result"]
    print(result["city"], result["now"]["temperature"], result["now"]["weather"])

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 {
   
        String host = "网关接入地址";
        String appcode = "你的APPCODE";
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(host + "?ip=8.8.8.8"))
                .header("Authorization", "APPCODE " + appcode)
                .build();
        HttpResponse<String> response =
                client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

PHP

<?php
$host = "网关接入地址";
$appcode = "你的APPCODE";
$ch = curl_init($host . "?ip=8.8.8.8");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Authorization: APPCODE " . $appcode]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$body = curl_exec($ch);
curl_close($ch);
$data = json_decode($body, true);
if ($data["code"] === 0) {
   
    echo $data["result"]["city"];
}

Node.js

const https = require("https");
const host = "网关接入地址";
const appcode = "你的APPCODE";

const req = https.get(
  `${
     host}?ip=8.8.8.8`,
  {
    headers: {
    Authorization: `APPCODE ${
     appcode}` } },
  (res) => {
   
    let buf = "";
    res.on("data", (c) => (buf += c));
    res.on("end", () => {
   
      const data = JSON.parse(buf);
      if (data.code === 0) console.log(data.result.city);
    });
  }
);
req.on("error", (e) => console.error(e));

六、在线调试实录

在商品页的在线调试 / API 网关调试台中，填入 APPCODE 鉴权头与查询参数即可发起请求。典型走查如下：

1. 选择查询维度（本文以 IP 为例），在参数区填入客户端 IP 或坐标。
2. 在请求头中填写 Authorization: APPCODE <appcode>。
3. 发起调用，观察 HTTP 状态码为 200 且业务 code 为 0。
4. 从 result.now 取实况，从 result.forecast 取预报数组。
5. 若返回非 200 或业务 code 非 0，按错误码表定位原因后再重试。

调试时的一个常见现象是：不同查询维度返回的城市层级可能不同（城市级 vs 区县级），下游应兼容处理 area 为空的情况。

七、接口调用限制与规范

为保障服务的公平使用，调用需遵守以下事实性约束（精确配额以控制台实时配置为准）：

• 频率约束：单凭证存在每秒请求数（QPS）与每日调用总量的上限，超出后网关返回限流错误。
• 消耗规则：仅在 HTTP 响应状态码为 200 时扣减调用次数，非 200 不计入消耗。
• 参数规范：查询维度需二选一，避免同时传冲突参数；坐标需为合法经纬度范围。
• 编码规范：请求与返回均为 UTF-8；参数值需做 URL 编码。
• 合规要求：不得将接口用于违法用途，不得对返回数据做误导性的二次加工与发布。
• 封禁说明：高频恶意请求、密钥泄露滥用等行为可能导致凭证被限制。

八、能力边界与免责声明

支持的能力

• 按地名、经纬度、区号邮编、IP、景点名查询天气。
• 当前 24 小时逐时、未来 7 天与 15 天预报、历史天气查询。
• 覆盖全国区县级以上城市与部分景点。

不支持 / 边界

• 分钟级雷达、公里级网格预报等高精度气象不在常规返回范围。
• 海外地点的覆盖以商品页说明为准，并非全球任意坐标都可用。
• 极端天气预警、专业航空气象等不在通用接口范畴。

免责声明

• 返回数据仅供参考，不构成任何业务决策、出行或作业的唯一依据。
• 数据存在更新延迟，实时以官方气象发布为准。
• 接口方不对因数据延迟、缺漏或误用导致的后果承担责任。
• 调用方应自行评估数据在关键场景下的适用性，并保留必要的冗余判断。

九、错误码与排查指南

排查顺序建议：先确认鉴权头 → 再核对参数组合 → 最后观察限流与网络。

十、常见问题 FAQ

Q1：支持哪些查询方式？
支持地名、经纬度坐标、区号/邮编、IP 地址、景点名称，不同方式对应商品页提供的不同接入地址。

Q2：数据多久刷新一次？
实况与预报的刷新频率由数据源决定，通常以小时级更新，具体以接口返回中的时间字段为准。

Q3：能不能高并发批量查询？
可以合规地多并发调用，但需遵守单凭证的 QPS 与日配额约束，建议在客户端做频控与缓存。

Q4：历史天气能查多远？
历史区间以商品页说明为准，并非任意历史日期都可用，调用前请确认覆盖范围。

Q5：经纬度查询的精度如何？
返回层级一般为城市或区县，不提供门牌级定位，下游不应依赖其做精确定位判断。

Q6：如何兼容不同城市的返回差异？
对 area、forecast 等字段做存在性校验，缺失时降级处理，避免解析异常。

十一、内容小结

天气数据查询 API 通过多种地理标识入参，提供当前实况、24 小时逐时、未来 7/15 天预报与历史天气，覆盖全国区县级以上区域。接入时需在请求头携带 APPCODE，按维度组织参数并解析 result 节点；工程中应补充参数校验、频控、重试、缓存与监控，并严格遵守能力边界与免责声明。精确配额与接入地址以控制台/商品页实时配置为准，发布前建议核对。