Windy气象API调用方法与气象数据接口获取步骤

接入Windy的全球气象数据并不复杂，但前提是先理清其独特的参数依赖规则。很多开发者都会遇到这样的情况：文档看了不少，示例也照着跑了，结果却返回400错误或空响应。通常这并不是代码本身的问题，而是Windy的参数依赖逻辑和模型匹配规则相对复杂。下面将关键步骤逐一说明。

第一步：注册并获取合法API Key

首先，需要注册开发者账号。完成邮箱验证后，进入控制台，点击“Create new key”，选择“Point Forecast API v2”类型，系统会自动生成一串32位字母数字组合的Key。这一步非常基础，【没有有效Key，后续所有请求都会被拒绝】。

还需注意，免费版每分钟最多支持10次请求，超过限制后会返回429错误。如果需要在生产环境中运行定时任务，建议提前升级付费套餐，否则频繁中断会影响任务稳定性。

确认目标区域可用的气象模型

Windy的模型选择并非通用，不同经纬度坐标仅支持特定模型。例如，海南三亚可使用gfs或cams，而法国巴黎则支持iconEU、arome以及ecmwf。若模型选择错误，请求会直接失败，错误提示通常只显示“invalid model”，不会进一步说明可用模型。

确认方法较为简单。可以打开Windy网页版，将地图放大到目标位置，右下角状态栏会显示当前加载的模型名称，例如“GFS 0.25°”，这通常就是接口中model参数可使用的合法值。

另一种更稳妥的方法是调用模型探测接口，传入坐标后，返回的JSON中会列出所有可用的模型缩写，从中选择支持所需参数的模型即可。

构造POST请求体并发送

在构造请求体时，有几个细节需要重点留意。首先，lat和lon必须为数字类型，不能写成字符串。小数位建议保留3到5位，超过6位时可能会被截断，从而导致定位偏移。

其次，parameters数组只能填写Windy明确支持的参数名。例如，gfs模型支持“wind”，但不支持“uv”；如果需要紫外线数据，则应改用cams模型。只要其中任意一个参数填写错误，整个数组都可能被忽略，返回结果中对应字段也会为空。

另外，levels参数虽然不是必填项，但如果需要获取850hPa高度的温度，就必须显式传入["850h"]，并且该level必须存在于availLevels返回列表中。否则，Windy会静默忽略该level设置，直接返回地表数据。

一个完整的body示例如下：

{
  "lat": 23.118,
  "lon": 113.254,
  "model": "gfs",
  "parameters": ["wind", "temp", "rh"],
  "key": "JEexHogRy9RENJWr6BFzlhH8NaWDfkk5"
}

可使用curl或requests向指定端点发送POST请求。响应头中的Content-Type应为application/json，状态码为200时才表示请求成功。

解析返回数据的时间轴结构

Windy返回的数据并不是按统一固定时间间隔排列的。gfs模型通常每3小时返回一组数据，例如0h、3h、6h等；而ECMWF可能只返回0h、6h、12h、24h、36h、48h、72h共7组数据。各组中的时间戳采用ISO 8601字符串格式，而不是Unix时间戳，这一点需要特别注意。

关键字段路径为response["data"]["properties"]["timeseries"]，这是主数据数组。数组中的每一项都包含time和data对象，其中data里的字段名与请求时填写的parameters完全一致。例如，当请求["wind"]时，data.wind将是一个包含u（东向风速）和v（北向风速）的对象。

还需要注意的是，【wind参数返回的是矢量分量，并非直接给出风速和风向；需要自行计算 magnitude = sqrt(u+v)，direction = atan2(u,v)】。这一点在实际解析中非常关键，也很容易被忽略。