综合

综合接口一次请求打包返回 realtime、minutely、hourly、daily 数据；alert=true 且 token 具备预警权限时附带 alert 预警数据。

更新频率与空间分辨率

综合接口返回的数据沿用各子数据类型的更新频率和空间分辨率，详情见 时空变量覆盖情况。

数据类型	更新频率	空间分辨率
实况数据	分钟级滚动发布（通常 1-5 分钟）	1 km 级（局地受站点覆盖影响）
分钟级降水数据	分钟滑动发布（发布周期约 5 分钟，时间分辨率 1 分钟）	1 km 级
逐小时数据	近时效滚动发布（发布周期约 5-15 分钟） 其余时段批量发布（约 1 小时级）	9-13 km 级（前 2 小时降水相关可细化至 1 km 级）
逐日数据	批量发布（通常 2-4 次/日）	9-13 km 级（由逐小时聚合）

预警信息同中央气象台同步，按预警发布区域和行政区划返回，不适用栅格空间分辨率。

请求

GET https://api.caiyunapp.com/v2.6/{token}/{经度},{纬度}/weather

路径参数

参数	说明
token	API 认证凭证，详见 认证与鉴权
经度	目标地点经度
纬度	目标地点纬度

注意：URL 路径中经度在前、纬度在后（如 101.6656,39.2072）；响应中的 location 字段为 [纬度, 经度] 顺序（如 [39.2072, 101.6656]）。

查询参数

名称	必填	默认值	取值范围	说明
lang	否	zh_CN	zh_CN/zh_TW/en_US/en_GB/ja	自然语言描述的语言，未匹配时回落 zh_CN，见 语言
unit	否	metric	metric/metric:v1/metric:v2/SI/imperial	单位制，其他取值返回 422，见 单位制
alert	否	false	true/false	alert=true 且 token 具备预警权限时，响应附带 result.alert，见 预警数据
callback	否	-	-	JSONP 回调函数名
dailysteps	否	5	1~16	返回的天数；通常为 1~15 天，dailysteps=16 需配合 dailystart=-1；实际上限由套餐决定，超出套餐上限时按套餐上限返回
dailystart	否	0	-1/0	仅支持 -1 和 0（-1 表示回退一天），其他取值返回 422
hourlysteps	否	48	1~360	返回的小时数，建议取 24 的整数倍；实际上限由套餐决定，超出套餐上限时按套餐上限返回

请求示例

curl "https://api.caiyunapp.com/v2.6/TAkhjf8d1nlSlspN/116.3176,39.9760/weather?alert=true&dailysteps=1&hourlysteps=24"

{
  "status": "ok", // 返回状态
  "api_version": "v2.6", // API 版本
  "api_status": "active", // API 状态
  "lang": "zh_CN", // 语言
  "unit": "metric", // 单位
  "tzshift": 28800, // 时区偏移
  "timezone": "Asia/Shanghai", // 时区
  "server_time": 1640758065, // 服务器时间
  "location": [39.976, 116.3176], // 地理位置
  "result": {
    "alert": {
      // 预警信息
    },
    "realtime": {
      // 实时天气数据
    },
    "minutely": {
      // 分钟级降水数据
    },
    "hourly": {
      // 小时级降水数据
    },
    "daily": {
      // 天级降水数据
    },
    "primary": 0, // 主要数据
    "forecast_keypoint": "未来两小时不会下雨，放心出门吧" // 天气预报关键点
  }
}

响应字段

JSONPath $.result.	说明
realtime	实况数据块，字段见 实况
minutely	分钟级数据块，字段见 分钟级预报；token 无分钟级权限时不返回该块
hourly	小时级数据块，字段见 小时级别预报
daily	天级数据块，字段见 天级别预报
alert	预警数据块（alert=true 且具备预警权限时返回），字段见 预警数据
primary	恒为 0
forecast_keypoint	天气预报关键点文案，见下方说明

description 与 forecast_keypoint

综合接口中二者含义不同：

• result.hourly.description：未来 24 小时天气变化描述，与单独调用小时级接口时的 description 一致。
• result.forecast_keypoint：通常为分钟级的未来 2 小时降水文案；但当分钟级数据无雷达覆盖，或分钟级无雨而未来 24 小时有雨时，采用逐小时的 24 小时文案。

错误

接口错误统一返回如下结构，HTTP 状态码与含义详见 错误信息。

{
  "status": "failed",
  "error": "token is invalid",
  "api_version": "2.6"
}