区域裁切统一接口

访问限制

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

按数据源（source）、区域（area_id）和变量（variable）获取区域裁切产物的下载地址。默认返回该变量最新起报批次，也可通过 base_time 指定某一批次。

新接入的数据源（当前为 ecmwf）统一使用本接口；已有数据源仍使用各自的接口，见本栏其它页面。

请求

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

• 错误信息

路径参数

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

查询参数

参数	必填	默认值	取值范围	说明
token	是	—	—	API 认证凭证，详见 认证与鉴权
source	是	—	ecmwf	数据源标识，取值与开通的数据源一致
variable	是	—	—	变量 shortName，如 2t；一次请求返回一个变量
base_time	否	最新起报	ISO 8601 UTC 或 YYYYMMDDHH	指定起报批次，如 2026-07-20T12:00:00Z 或 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"
}

响应字段

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

注意事项

• url 包含认证参数 auth_key，有效期有限（1 小时），请及时使用；过期后重新请求本接口获取新的下载地址
• 实际可用的 source、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)

# 文件内包含的预报时效（小时）
print(ds["step"].values)

支持产品

ecmwf

当前统一接口首发产品。请求时 source 取 ecmwf。

项	说明
数据来源	ECMWF IFS 预报（forecast）产品
数据格式	NetCDF；一个变量一个文件，文件内含该批次全部已裁切的预报时效
元信息	自描述网格数据文件，文件内部包含经纬度、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

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