GFS 土壤数据区域预测 API

API 概述

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

API 地址

请求方法： GET

端点 URL：

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

• 认证与鉴权 | 错误信息

请求参数

参数名	类型	是否必填	描述
area_id	int	是	区域唯一标识符
token	string	是	接口认证密钥（Token）

响应格式

响应为 JSON 对象，结构如下：

{
  "area_id": "区域ID",
  "batch_time": "批处理时间（ISO 8601）",
  "items": [
    {
      "variable": "变量名称",
      "url": "数据文件下载链接（含认证密钥）"
    }
  ]
}

字段说明

字段名	类型	描述
area_id	string	请求区域 ID，与请求路径中的 area_id 相同
batch_time	string	批处理时间，ISO 8601 格式（UTC）
items	array	土壤变量数据列表
└ variable	string	变量名称，遵循命名规则（见下）
└ url	string	对应变量的数据文件下载地址

示例响应

{
  "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=..."
    }
  ]
}

变量命名规则

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

变量名称含义对照表

变量简称	全称	单位	含义说明
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)