土壤温湿数据区域裁切

API 概述

本 API 提供基于 GFS（Global Forecast System）模型的土壤数据预测结果，支持按区域（area_id）获取预测数据文件列表，结果以 JSON 格式返回。

请求

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

• 错误信息

路径参数

参数	说明
area_id	区域唯一标识符

查询参数

参数	必填	默认值	取值范围	说明
token	是	—	—	API 认证凭证，详见 认证与鉴权

请求示例

curl "https://singer.caiyunhub.com/v3/ud/gfs_soil/region_cut/{area_id}?token={token}"

响应示例

{
  "area_id": "41",
  "batch_time": "2025-06-03T18:00:00Z",
  "items": [
    {
      "variable": "soill_0-10-40-100cm",
      "url": "http://foo.bar/.../soill_depthBelowLandLayer_0_3_192.nc?auth_key=..."
    },
    {
      "variable": "soill_100-200cm",
      "url": "http://foo.bar/.../soill_depthBelowLandLayer_1_3_192.nc?auth_key=..."
    },
    {
      "variable": "soilw_0-10-40-100cm",
      "url": "http://foo.bar/.../soilw_depthBelowLandLayer_0_0_192.nc?auth_key=..."
    },
    {
      "variable": "soilw_100-200cm",
      "url": "http://foo.bar/.../soilw_depthBelowLandLayer_1_0_192.nc?auth_key=..."
    },
    {
      "variable": "st_0-10-40-100cm",
      "url": "http://foo.bar/.../st_depthBelowLandLayer_0_0_2.nc?auth_key=..."
    },
    {
      "variable": "st_100-200cm",
      "url": "http://foo.bar/.../st_depthBelowLandLayer_1_0_2.nc?auth_key=..."
    }
  ]
}

响应字段

JSONPath	类型	说明
$.area_id	string	请求区域 ID，与请求路径中的 area_id 相同
$.batch_time	string	批处理时间，ISO 8601 格式（UTC）
$.items	array<object>	土壤变量数据列表
$.items[].variable	string	变量名称，遵循变量命名规则
$.items[].url	string	对应变量的数据文件下载地址

变量命名规则

命名格式：{变量简称}_{深度标识}

变量名称含义对照表

变量简称	全称	单位	含义说明
st	Soil Temperature	K（开尔文）	土壤温度，是地表以下各层土壤的温度预测值
soilw	Volumetric Soil Moisture Content	m³/m³	体积土壤含水量（即液态水 + 冰，若存在）。反映土壤总体含水能力
soill	Liquid Volumetric Soil Moisture Content (non-frozen)	m³/m³	液态体积含水量（不含冰冻水），更适用于实际可利用水分的估算

深度标识说明

标识	对应深度层级（单位：cm）
0-10-40-100cm	含 0–10cm、10–40cm、40–100cm 三个深度层
100-200cm	单层深度，表示 100–200cm 层土壤数据

注意事项

• 每个 url 包含认证参数 auth_key，有效期有限（1 小时），请及时使用或刷新
• 返回文件格式通常为 NetCDF（.nc），适用于气象及地学数据处理

NetCDF 文件读取示例

import xarray as xr

file_path = "your_file_path.nc"

ds = xr.open_dataset(file_path)