小时级别预报

返回指定地点逐小时的天气预报数据，包括气温、体感温度、风、降水、云量、天气现象和空气质量等。

更新频率与空间分辨率

逐小时数据在近时效为高频刷新（约 5-15 分钟），其余时段为批次发布（约 1 小时级）；空间分辨率为 9-13 km 级（前 2 小时降水相关结果可细化至 1 km 级），时间范围为未来十五天逐小时。详情见 时空变量覆盖情况。

请求

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

路径参数

参数	说明
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 包装
hourlysteps	否	48	1~360	控制返回多少小时的数据，建议取 24 的整数倍；实际上限由套餐决定，超出套餐上限时按套餐上限返回

请求示例

curl "https://api.caiyunapp.com/v2.6/TAkhjf8d1nlSlspN/101.6656,39.2072/hourly?hourlysteps=1"

{
  "status": "ok", // 返回状态
  "api_version": "v2.6", // API 版本
  "api_status": "active", // API 服务状态
  "lang": "zh_CN", // 返回语言
  "unit": "metric", // 单位
  "tzshift": 28800, // 时区偏移
  "timezone": "Asia/Shanghai", // 时区
  "server_time": 1653552908, // 服务器时间
  "location": [39.2072, 101.6656], // 请求经纬度，[纬度, 经度] 顺序
  "result": {
    "hourly": {
      "status": "ok",
      "description": "未来24小时阴", // 未来 24 小时天气变化自然语言描述（生成失败时为空字符串）
      "precipitation": [ // 降水数据
        {
          "datetime": "2022-05-26T16:00+08:00",
          "value": 0, // 降水量
          "probability": 0 // 降水概率(0~100)
        }
      ],
      "temperature": [ // 地表 2 米气温
        {
          "datetime": "2022-05-26T16:00+08:00",
          "value": 27
        }
      ],
      "apparent_temperature": [ // 体感温度
        {
          "datetime": "2022-05-26T16:00+08:00",
          "value": 24.6
        }
      ],
      "wind": [ // 地表 10 米风向和风速
        {
          "datetime": "2022-05-26T16:00+08:00",
          "speed": 9, // 风速
          "direction": 104 // 风向
        }
      ],
      "humidity": [ // 地表 2 米相对湿度
        {
          "datetime": "2022-05-26T16:00+08:00",
          "value": 0.12
        }
      ],
      "cloudrate": [ // 云量
        {
          "datetime": "2022-05-26T16:00+08:00",
          "value": 0
        }
      ],
      "skycon": [ // 天气现象
        {
          "datetime": "2022-05-26T16:00+08:00",
          "value": "CLEAR_DAY"
        }
      ],
      "pressure": [ // 地面气压
        {
          "datetime": "2022-05-26T16:00+08:00",
          "value": 84020.8379904
        }
      ],
      "visibility": [ // 地表水平能见度
        {
          "datetime": "2022-05-26T16:00+08:00",
          "value": 25
        }
      ],
      "dswrf": [ // 向下短波辐射通量
        {
          "datetime": "2022-05-26T16:00+08:00",
          "value": 736.87204608
        }
      ],
      "air_quality": { // 空气质量
        "aqi": [ // AQI
          {
            "datetime": "2022-05-26T16:00+08:00",
            "value": {
              "chn": 78, // 国标 AQI
              "usa": 54 // 美标 AQI
            }
          }
        ],
        "pm25": [ // PM2.5 浓度
          {
            "datetime": "2022-05-26T16:00+08:00",
            "value": 14
          }
        ]
      }
    },
    "primary": 0,
    "forecast_keypoint": "未来24小时阴" // 天气预报关键点（与 hourly.description 内容一致）
  }
}

响应字段

JSONPath $.result.hourly.	说明
temperature[].value	地表 2 米气温
apparent_temperature[].value	体感温度
pressure[].value	地面气压
humidity[].value	地表 2 米相对湿度(0-1)
wind[].direction	地表 10 米风向（条目结构为 {datetime, speed, direction}，无嵌套 value）
wind[].speed	地表 10 米风速（条目结构同上）
precipitation[].value	降水数据
precipitation[].probability	降水概率(0~100, 单位 %)；仅前 2 小时为连续概率（由雷达概率改写）
cloudrate[].value	云量(0.0-1.0)
dswrf[].value	向下短波辐射通量(W/M2)
visibility[].value	地表水平能见度
skycon[].value	天气现象
air_quality.pm25[].value	PM2.5 浓度(μg/m3)
air_quality.aqi[].value.chn	国标 AQI，详见 环境空气质量
air_quality.aqi[].value.usa	美标 AQI，详见 环境空气质量
description	未来 24 小时天气变化自然语言描述；生成失败时为空字符串

JSONPath $.result.	说明
forecast_keypoint	自然语言描述，与 hourly.description 内容一致

description 与 forecast_keypoint

小时级接口中，description（位于 result.hourly）与 forecast_keypoint（位于 result）内容一致，均表示未来 24 小时的天气变化描述，可直接用于展示或摘要。

备注

• 各数组条目从当前整点时刻起，长度等于实际生效的 hourlysteps；datetime 为目标地点时区的 ISO 串（如 2022-05-26T16:00+08:00）。
• hourlysteps 非 24 的整数倍时可能返回失败。

错误

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

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