PolyWeather API 接口文档 (v1.0)

本文档详细介绍了 PolyWeather 后端提供的 RESTful API 接口。该后端基于 FastAPI 构建，主要为前端地图和终端面板提供实时天气分析、模型预测及历史对账数据。

1. 基础信息

Base URL: http://127.0.0.1:8000 (本地) 或 https://your-vps-ip:8000 (服务器)
数据格式: JSON
速率限制: 默认无限制，建议前端缓存时间 5 分钟。

2. 接口列表

2.1 获取城市列表

返回所有受监控的城市及其基础坐标和风险等级。

URL: /api/cities
Method: GET
返回示例:

{
  "cities": [
    {
      "name": "ankara",
      "display_name": "Ankara",
      "lat": 39.93,
      "lon": 32.85,
      "risk_level": "medium",
      "risk_emoji": "🟡",
      "airport": "Esenboga",
      "icao": "LTAC",
      "temp_unit": "celsius",
      "is_major": true
    }
  ]
}

2.2 获取城市详情分析

获取指定城市的实时实测数据、多模型预测对比、DEB 算法预测以及 AI 决策建议。

URL: /api/city/{name}
Method: GET
参数:
- name (string): 城市名称或别名（不区分大小写，如 ankara, ldn）。
- force_refresh (bool, optional): 是否强制跳过缓存刷新数据。默认 false。
返回示例:

{
  "name": "ankara",
  "display_name": "Ankara",
  "lat": 39.93,
  "lon": 32.85,
  "temp_symbol": "°C",
  "local_time": "2024-03-08 10:30:00",
  "risk": {
    "level": "medium",
    "warning": "模型分歧较大",
    "icao": "LTAC"
  },
  "current": {
    "temp": 12.5,
    "max_so_far": 14.2,
    "obs_time": "10:20",
    "wx_desc": "Cloudy"
  },
  "multi_model": {
    "ECMWF": 15.1,
    "GFS": 14.8,
    "MGM": 15.5
  },
  "deb": {
    "prediction": 15.2
  },
  "ai_analysis": "当前模型一致性较好，建议参考 DEB 预测值..."
}

2.3 获取历史对账数据

获取指定城市的过去几天内的预测值与真实最高温的对比记录，用于评估模型准确率。

URL: /api/history/{name}
Method: GET
参数:
- name (string): 城市名称。
返回示例:

{
  "history": [
    {
      "date": "2024-03-07",
      "actual": 14.0,
      "deb": 14.2,
      "mu": 14.1,
      "mgm": 14.5
    }
  ]
}

3. 核心对象定义

3.1 风险等级 (Risk Level)

low (🟢): 预测一致，波动小。
medium (🟡): 存在轻微模型分歧或数据延迟。
high (🔴): 模型严重打架，市场风险极高。

3.2 预测模型 (Models)

ECMWF: 欧洲中期天气预报中心（全球最准）。
GFS: 美国全球预测系统。
MGM: 土耳其国家气象局（针对特定城市非常精准）。
DEB: PolyWeather 独家加权融合算法成果。

4. 数据来源与第三方 API

系统通过多源聚合链路确保数据的真实性与前瞻性，以下是目前集成的核心数据源：

4.1 核心实测数据 (Settlement Data)

NOAA Aviation Weather (METAR): 全球机场官方航空气象报文，也是 Polymarket 官方结算参考源。
Iowa Mesonet (IEM): 提供 1-5 分钟级别的超高频 ASOS/METAR 实时观测，是高频交易对账的核心源。
MGM (土耳其国家气象局): 提供土耳其境内（如安卡拉）最精细的本地观测站数据。

4.2 模型预测数据 (Forecast Data)

Open-Meteo: 聚合 ECMWF (欧洲中期)、GFS (美国)、ICON (德国) 等全球顶级大型数值预报模型。
Meteoblue: 针对地形复杂的城市提供高精度修正预测（需 API Key）。
NWS (美国气象局): 美国本土城市的官方权威预报。

4.3 智能化分析

Groq API: 驱动 AI 态势感知引擎，基于多源数据生成实时中文交易分析报告（需 API Key）。

5. 常见问题

404 Error: 检查城市名是否拼写正确，或是否在支持列表中。
500 Error: 后端与气象数据源（如 METAR）同步失败，通常 1 分钟后会自动恢复。
数据延迟: METAR 实测数据通常每 30-60 分钟更新一次。

4.1 KiB Raw Blame History