历史定量降水区域裁切

访问限制

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

历史定量降水是在雷达覆盖区域内，使用神经网络算法融合国控站点数据与雷达回波得到的累计 1 小时降水量数据，空间分辨率为 1 km × 1 km。按开通区域的经纬度边界裁出单个时次的 NetCDF。source 取 qpe，variable 取 precip。

数据说明

项	说明
数据来源	国控站点数据与雷达回波融合
数据格式	NetCDF；一个文件包含一个时次的 1 小时累计降水
元信息	文件内包含经纬度等必要元信息
数据时次	每 5 分钟一个时次（UTC）。指定 base_time 时分钟必须是 5 的倍数，如 202609210230、202609210235
空间范围	全国网格：经度 71.9282°E–150.6026°E，纬度 3.9079°N–57.9079°N。开通区域须落在此范围内，按区域边界裁切
空间分辨率	1 km × 1 km

支持变量

变量	变量说明
precip	1 小时累计降水，单位 mm

请求

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

• 错误信息 | 数据说明

路径参数

参数	说明
area_id	区域 ID，由商务开通时提供，格式为 {客户缩写}_{编号}，如 demo_440300

查询参数

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

本产品为历史实况数据，不包含预报时效维度。

请求示例

1. 获取最新时次：

curl "https://singer.caiyunhub.com/v3/ud/cut/demo_440300?source=qpe&variable=precip&token={token}"

2. 指定数据时次：

curl "https://singer.caiyunhub.com/v3/ud/cut/demo_440300?source=qpe&variable=precip&base_time=202609210235&token={token}"

base_time 必须是整 5 分钟

时次分钟只能是 00、05、10、15、20、25、30、35、40、45、50、55（UTC）。非整 5 分钟没有对应产物。

响应示例

{
  "source": "qpe",
  "area_id": "demo_440300",
  "variable": "precip",
  "base_time": "2026-09-21T02:35:00Z",
  "url": "https://meteorology.caiyuncdn.com/ud/prod/qpe/2026/09/21/0235/demo_440300/precip.nc?auth_key=1790000000-68a5f1c0f31b9c578d5f5801-0-cb7ec1deafe05f5fc7c625dd8f3f5e93",
  "expires_at": 1790000000
}

响应字段

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

注意事项

• base_time 必须是整 5 分钟（UTC），非整 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)
print(ds)