以下场景都可以通过该接口实现：

• 查询当前天气、体感温度、风力和空气质量
• 拉取未来几小时降水、温度和能见度序列
• 获取未来几天天气、温差、日出日落和生活指数

背景说明

天气数据接入常见于内容展示、出行提醒、自动化任务和运维看板。实际对接时，开发者最关心的通常不是概念说明，而是接口链接怎么写、参数怎么传、返回字段在哪里取值，以及 Python 调用后如何稳定解析。

依赖安装

本文示例使用 requests：

pip install requests

基本信息

项目	内容
接口文档	https://apizero.cn/marketplace/weather
接口链接	https://v1.apizero.cn/api/weather
请求方式	GET
返回格式	JSON
支持能力	实时天气、分钟级降水、小时预报、天预报、综合数据
范围说明	小时预报文档说明最长 360 小时，天预报文档说明最长 15 天

该接口既可以用城市名查询，也可以用经纬度查询。常见 type 取值包括 realtime、minutely、hourly、daily、weather。

常见地址写法如下：

场景	地址示例
实时天气	https://v1.apizero.cn/api/weather?city=北京&type=realtime
天预报	https://v1.apizero.cn/api/weather?city=北京&type=daily&days=3

以下地址示例建议逐条演示，便于观察不同返回结构。

参数说明

参数名	类型	示例值	说明
type	string	weather	返回模块类型，常见取值为 realtime、minutely、hourly、daily、weather
city	string	北京	城市名查询参数，和 location 至少传一个
location	string	116.4074,39.9042	经纬度查询参数，格式为 经度,纬度，和 city 至少传一个
days	integer	3	天预报步长，适用于 daily 或 weather，文档说明最长 15 天
hours	integer	24	小时预报步长，适用于 hourly 或 weather，文档说明最长 360 小时
alert	boolean/string	false	是否返回预警列表；示例请求中传入 alert=false 时 alerts 为空

如果只想先验证返回结构，建议先从一条低频请求开始：

https://v1.apizero.cn/api/weather?city=北京&type=weather&days=3&hours=24

完整代码

下面的脚本只展示 2 种常见调用方式，分别对应实时天气和天预报。这样既能看清返回差异，也便于直接改成自己的参数。

import json
import time

import requests

BASE_URL = "https://v1.apizero.cn/api/weather"

# 以下示例仅展示 2 种常见调用方式，按需替换参数即可
SCENARIOS = [
    {
        "label": "实时天气",
        "params": {
            "city": "北京",
            "type": "realtime",
        },
    },
    {
        "label": "天预报",
        "params": {
            "city": "北京",
            "type": "daily",
            "days": 3,
        },
    },
]


def call_weather_api(params):
    response = requests.get(
        BASE_URL,
        params=params,
        headers={"Accept": "application/json"},
        timeout=20,
    )
    response.raise_for_status()
    payload = response.json()

    if payload.get("code") != 0:
        raise RuntimeError(
            f"接口返回异常: code={payload.get('code')} msg={payload.get('msg')}"
        )

    return payload


def extract_result(payload):
    data = payload.get("data") or {}
    location = data.get("location") or {}

    if data.get("type") == "realtime":
        realtime = data.get("realtime") or {}
        return {
            "city": location.get("city"),
            "type": data.get("type"),
            "server_time": data.get("server_time"),
            "temperature": realtime.get("temperature"),
            "humidity": realtime.get("humidity"),
            "visibility": realtime.get("visibility"),
            "skycon": realtime.get("skycon"),
        }

    daily = data.get("daily") or {}
    first_day = (daily.get("temperature") or [{}])[0]
    first_astro = (daily.get("astro") or [{}])[0]
    sunrise = (first_astro.get("sunrise") or {}).get("time")
    sunset = (first_astro.get("sunset") or {}).get("time")

    return {
        "city": location.get("city"),
        "type": data.get("type"),
        "server_time": data.get("server_time"),
        "first_day_max": first_day.get("max"),
        "first_day_min": first_day.get("min"),
        "sunrise": sunrise,
        "sunset": sunset,
    }


def main():
    results = []

    for idx, scenario in enumerate(SCENARIOS, start=1):
        if idx > 1:
            # 示例中相邻请求保留 1 秒间隔，便于观察返回结果
            time.sleep(1)

        payload = call_weather_api(scenario["params"])
        results.append(
            {
                "label": scenario["label"],
                "params": scenario["params"],
                "result": extract_result(payload),
            }
        )

    print(json.dumps(results, ensure_ascii=False, indent=2))


if __name__ == "__main__":
    main()

返回示例

成功返回时，顶层通常包含 code、msg、data 和 request_id。其中 data.type 决定了当前返回的模块结构。

以下结构截取自一次示例请求，时间字段已改成占位写法，便于长期复用：

{
  "code": 0,
  "msg": "成功",
  "data": {
    "type": "weather",
    "location": {
      "city": "北京",
      "longitude": 116.4074,
      "latitude": 39.9042,
      "timezone": "Asia/Shanghai"
    },
    "server_time": "YYYY-MM-DD HH:MM:SS",
    "forecast_keypoint": "返回的天气概览文本",
    "summary": {
      "skycon": "小雨",
      "temperature": 18.4,
      "humidity_percent": 94,
      "wind": {
        "direction_text": "东南风",
        "level_text": "和风"
      },
      "air_quality": {
        "aqi": 13,
        "level": "优",
        "pm25": 9
      },
      "alert_count": 0
    },
    "realtime": {
      "temperature": 18.36,
      "humidity": 0.94,
      "visibility": 11.15,
      "skycon": "LIGHT_RAIN"
    },
    "minutely": {
      "status": "ok",
      "precipitation_2h": [0.12, 0.13]
    },
    "daily": {
      "astro": [
        {
          "date": "YYYY-MM-DDT00:00+08:00",
          "sunrise": { "time": "04:57" },
          "sunset": { "time": "19:23" }
        }
      ]
    },
    "alerts": []
  },
  "request_id": "example_request_id"
}

常用字段可以先按下面这张表来取：

字段路径	说明
code	接口执行结果，0 表示成功
msg	结果说明文字
data.type	当前返回模块类型
data.location	查询位置，包含城市、经度、纬度、时区
data.summary	综合摘要，适合列表卡片快速展示
data.realtime	实时天气明细
data.minutely.precipitation_2h	分钟级降水序列
data.hourly.temperature	小时级温度序列
data.daily.temperature	逐日温度区间
data.daily.astro	日出日落信息
data.alerts	预警列表
request_id	请求标识，便于排查

实际调用时，下面几种状态码最值得先判断：

code	msg 示例	含义
0	成功	请求完成，可以继续解析 data
4000	city 与 location 至少传一个	缺少位置参数
4029	调用过快，请稍后再试	请求节奏过快，可结合 retry_after 调整

如果你的脚本主要做展示，优先读取 summary、realtime 和 alerts。如果你的脚本做趋势分析，优先读取 hourly 与 daily 下的数组字段，再按时间维度做映射即可。

小结

这类天气接口的接入重点很明确：先确认 city 或 location，再根据 type 缩小返回范围，最后按模块字段做解析。本文给出的两段低频 Python 调用和三种常见状态码，已经够你快速搭起一个稳定的天气查询脚本；具体字段扩展仍以接口文档为准。