分钟级雷达降水预报区域裁切

访问限制

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

全国分钟级雷达降水预报的区域裁切。开通区域须落在全国网格内，按该区域边界裁出 prate 的 NetCDF，文件内包含该起报批次全部预报时效。source 取 radar，variable 取 prate。

数据说明

项	说明
数据来源	全国分钟级雷达降水预报
数据格式	NetCDF；一个变量一个文件，文件内含该批次全部预报时效
元信息	文件内包含经纬度、step（单位分钟）、valid_time
起报时间	每 5 分钟一批（UTC）。指定 base_time 时分钟必须是 5 的倍数，如 202610120700、202610120705
预报时效	0–125 分钟，逐 5 分钟
空间范围	全国网格：经度 71.9282°E–150.6026°E，纬度 3.9079°N–57.9079°N。开通区域须落在此范围内，按该区域边界裁切
空间分辨率	约 1 km
产物保留	约 1 天，更早的起报批次可能已过期

支持变量

变量	变量说明
prate	降水率，单位 mm/h

请求

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

• 错误信息 | 数据说明

路径参数

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

查询参数

参数	必填	默认值	取值范围	说明
token	是	—	—	API 认证凭证，详见 认证与鉴权
source	是	—	radar	固定取 radar
variable	是	—	prate	降水率，见支持变量
base_time	否	最新起报	整 5 分钟（UTC）	指定起报批次，格式为 ISO 8601 UTC 或 YYYYMMDDHHMM。分钟只能是 00、05、10、15、20、25、30、35、40、45、50、55

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

请求示例

curl "https://singer.caiyunhub.com/v3/ud/cut/nanning_450100?source=radar&variable=prate&base_time=202610120700&token={token}"

base_time 必须是整 5 分钟

起报分钟只能是 00、05、10、15、20、25、30、35、40、45、50、55（UTC）。202610120700、202610120705 有效；202610120703 这类非整 5 分钟没有对应批次。

响应示例

{
  "source": "radar",
  "area_id": "nanning_450100",
  "variable": "prate",
  "base_time": "2026-10-12T07:00:00Z",
  "url": "https://meteorology.caiyuncdn.com/ud/prod/zarr/radar/2026/10/12/0700/nanning_450100/prate.nc?auth_key=1784548800-68a5f1c0f31b9c578d5f5801-0-cb7ec1deafe05f5fc7c625dd8f3f5e93",
  "expires_at": 1784548800
}

响应字段

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

注意事项

• base_time 必须是整 5 分钟（UTC），分钟只能是 00、05、…、55。非整 5 分钟没有对应批次
• 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"))