ECMWF 预报区域裁切

访问限制

本部分 API 属于增值服务，仅提供给企业套餐开发者，如需采购请联系彩云商务

ECMWF IFS 预报（forecast）的区域裁切。按开通区域的经纬度边界裁出单个变量的 NetCDF，文件内包含该起报批次全部已裁切的预报时效。source 取 ecmwf。

数据说明

项	说明
数据来源	ECMWF IFS 预报（forecast）产品
数据格式	NetCDF；一个变量一个文件，文件内含该批次全部已裁切的预报时效
元信息	自描述网格数据文件，文件内部包含经纬度、step 等必要的元信息。step 单位为小时
起报时间	每日 00、06、12、18 时（UTC）
预报时效	00、12 时起报：0–90h 逐 1 小时、93–144h 逐 3 小时、150–360h 逐 6 小时；06、18 时起报：0–90h 逐 1 小时、93–144h 逐 3 小时
空间范围	按开通区域的经纬度边界裁切
空间分辨率	0.1°
产物保留	约 7 天，更早的起报批次可能已过期

支持变量

变量	变量说明
2t	近地面 2m 处的气温：单位 K
tp	累积降水：单位 m

如需其它变量，请联系彩云商务开通。

请求

GET https://singer.caiyunhub.com/v3/ud/cut/{area_id}

• 错误信息 | 数据说明

路径参数

参数	说明
area_id	区域 ID，由商务开通时提供，如 nanning_450100

查询参数

参数	必填	默认值	取值范围	说明
token	是	—	—	API 认证凭证，详见 认证与鉴权
source	是	—	ecmwf	固定取 ecmwf
variable	是	—	2t、tp	变量 shortName，一次请求返回一个变量，见支持变量
base_time	否	最新起报	每日 00、06、12、18 时（UTC）	指定起报批次。格式为 ISO 8601 UTC 或 YYYYMMDDHH，如 2026072012

本接口不提供 step、hours 等预报时效过滤参数：预报时效在文件内的 step 维中，单个文件包含该变量该批次全部已裁切的 step。

请求示例

1. 获取最新起报批次：

curl "https://singer.caiyunhub.com/v3/ud/cut/nanning_450100?source=ecmwf&variable=2t&token={token}"

2. 指定起报批次：

curl "https://singer.caiyunhub.com/v3/ud/cut/nanning_450100?source=ecmwf&variable=2t&base_time=2026072012&token={token}"

响应示例

{
  "source": "ecmwf",
  "area_id": "nanning_450100",
  "variable": "2t",
  "base_time": "2026-07-20T12:00:00Z",
  "url": "https://meteorology.caiyuncdn.com/ud/prod/zarr/2026/07/20/12/nanning_450100/2t.nc?auth_key=1784548800-68a5f1c0f31b9c578d5f5801-0-cb7ec1deafe05f5fc7c625dd8f3f5e93",
  "expires_at": 1784548800
}

响应字段

JSONPath	类型	说明
$.source	string	数据源标识，与请求参数一致，本产品为 ecmwf
$.area_id	string	区域 ID，与请求路径一致
$.variable	string	变量名，与请求参数一致
$.base_time	string	该文件的起报时间，ISO 8601 格式（UTC）
$.url	string	NetCDF 文件下载地址（含临时认证参数 auth_key）
$.expires_at	number	url 的过期时间，Unix 时间戳（秒）

注意事项

• url 包含认证参数 auth_key，过期时间见 expires_at（1 小时）；过期后重新请求本接口获取新的下载地址
• 实际可用的 area_id 与变量以开通范围为准，未开通的组合返回 401
• 库中暂无对应产物时返回 404（no data found），与权限失败区分

错误

场景	典型响应
未传或无效的 token	401，鉴权失败
token 未开通该 source 与 area_id	401，无权限
缺少 source 或 variable，或 base_time 格式非法	400，BAD_PARAM
无对应产物	404，NOT_FOUND（no data found）

详见 错误信息。

NetCDF 文件读取示例

import xarray as xr

file_path = "your_file_path.nc"

ds = xr.open_dataset(file_path)

# 预报时效在 step 维，单位为小时
print(ds["step"].values)
print(ds["step"].attrs.get("units"))