Caiyun Weather
Prerequisites
- Get API access and your API key from https://docs.caiyunapp.com/weather-api/.
- Credentials are resolved in order:
1. $CAIYUN_WEATHER_API_TOKEN environment variable 2. ~/.config/caiyunapp/config.json — JSON key caiyun_weather_api_token
- Requires coordinates. Ask for latitude and longitude if they are missing.
Quick Start
curl -s "https://api.caiyunapp.com/v2.6/${CAIYUN_WEATHER_API_TOKEN}/<lon>,<lat>/weather?hourlysteps=24&dailysteps=5&unit=metric:v2"Workflow
- Confirm coordinates are available.
- Confirm credentials are available:
- Check $CAIYUN_WEATHER_API_TOKEN env var first. - If absent, read the config file: cat ~/.config/caiyunapp/config.json and extract caiyun_weather_api_token. - If both are missing, tell the user to set the env var or create the config file.
- Run the curl command with the resolved token:
curl -s "https://api.caiyunapp.com/v2.6/<token>/<lon>,<lat>/weather?hourlysteps=24&dailysteps=5&unit=metric:v2"- Summarize results in this order when relevant:
- current conditions from result.realtime - near-term change from result.forecast_keypoint - 24-hour trend from result.hourly.description - daily highs, lows, or sky conditions from result.daily
- Return raw JSON only when the user asks for it.
Defaults
- Returned values are interpreted using
metric:v2units (see Field Reference below). - Use
hourlysteps=24unless the user requests a different horizon. - Use
dailysteps=5unless the user requests a different day count.
Failure Handling
- If credentials are missing, explain how to set
CAIYUN_WEATHER_API_TOKENor create~/.config/caiyunapp/config.jsonwith{"caiyun_weather_api_token": "<your_token>"}. - If coordinates are missing, ask for latitude and longitude.
- If the API response status is not
ok, report the HTTP status and API status payload.
Field Reference
Endpoint
GET https://api.caiyunapp.com/v2.6/{API_KEY}/{lon},{lat}/weatherSupported query parameters:
hourlysteps— number of hourly forecast steps (default: 24)dailysteps— number of daily forecast steps (default: 5)
Key Response Fields
result.realtime: current conditions (temperature, humidity, wind, skycon, visibility, pressure, apparent_temperature, precipitation)result.minutely: minute-level precipitation forecast for the next 2 hoursresult.hourly: hourly forecast data (temperature, precipitation, wind, skycon, humidity, cloudrate, pressure, visibility)result.daily: multi-day forecast data (temperature min/max, precipitation, wind, skycon, humidity, cloudrate, pressure, visibility, life_index)result.forecast_keypoint: short-term highlight summary for the next 2 hoursresult.hourly.description: longer 24-hour narrative string
Units (metric:v2)
| Field | Unit |
|---|---|
| temperature | °C |
| wind speed | km/h |
| wind direction | 0–360° clockwise from north |
| pressure | Pa |
| humidity | 0–1 |
| cloudrate | 0–1 |
| precipitation (realtime/minutely/hourly/daily) | mm/h |
| visibility | km |
Skycon Codes
| Code | Chinese | English |
|---|---|---|
CLEAR_DAY | 晴（白天） | Clear day |
CLEAR_NIGHT | 晴（夜间） | Clear night |
PARTLY_CLOUDY_DAY | 多云（白天） | Partly cloudy day |
PARTLY_CLOUDY_NIGHT | 多云（夜间） | Partly cloudy night |
CLOUDY | 阴 | Cloudy |
LIGHT_HAZE | 轻度雾霾 | Light haze |
MODERATE_HAZE | 中度雾霾 | Moderate haze |
HEAVY_HAZE | 重度雾霾 | Heavy haze |
LIGHT_RAIN | 小雨 | Light rain |
MODERATE_RAIN | 中雨 | Moderate rain |
HEAVY_RAIN | 大雨 | Heavy rain |
STORM_RAIN | 暴雨 | Storm rain |
FOG | 雾 | Fog |
LIGHT_SNOW | 小雪 | Light snow |
MODERATE_SNOW | 中雪 | Moderate snow |
HEAVY_SNOW | 大雪 | Heavy snow |
STORM_SNOW | 暴雪 | Storm snow |
DUST | 浮尘 | Dust |
SAND | 沙尘 | Sand |
WIND | 大风 | Wind |
Priority order: snow > rain > fog > sand > dust > haze > wind > cloudy > partly cloudy > clear.
Precipitation Intensity Thresholds
| Hourly (mm/h) | Minutely (mm/h) | Meaning |
|---|---|---|
< 0.0606 | < 0.08 | No rain or snow |
0.0606–0.8989 | 0.08–3.44 | Light rain or snow |
0.8989–2.87 | 3.44–11.33 | Moderate rain or snow |
2.87–12.8638 | 11.33–51.30 | Heavy rain or snow |
≥ 12.8638 | ≥ 51.30 | Storm rain or snow |
Wind Speed Scale (km/h)
| Level | Speed range | Description |
|---|---|---|
| 0 | < 1 | Calm |
| 1 | 1–5 | Light air |
| 2 | 6–11 | Light breeze |
| 3 | 12–19 | Gentle breeze |
| 4 | 20–28 | Moderate breeze |
| 5 | 29–38 | Fresh breeze |
| 6 | 39–49 | Strong breeze |
| 7 | 50–61 | High wind |
| 8 | 62–74 | Gale |
| 9 | 75–88 | Strong gale |
| 10 | 89–102 | Storm |
| 11 | 103–117 | Violent storm |
| 12 | 118–133 | Hurricane |
| 13 | 134–149 | Typhoon |
| 14 | 150–166 | Strong typhoon |
| 15 | 167–183 | Strong typhoon |
| 16 | 184–201 | Super typhoon |
| 17 | 202–220 | Super typhoon |
Wind Direction (16-point)
| Direction | Degrees |
|---|---|
| N | 348.76–11.25 |
| NNE | 11.26–33.75 |
| NE | 33.76–56.25 |
| ENE | 56.26–78.75 |
| E | 78.76–101.25 |
| ESE | 101.26–123.75 |
| SE | 123.76–146.25 |
| SSE | 146.26–168.75 |
| S | 168.76–191.25 |
| SSW | 191.26–213.75 |
| SW | 213.76–236.25 |
| WSW | 236.26–258.75 |
| W | 258.76–281.25 |
| WNW | 281.26–303.75 |
| NW | 303.76–326.25 |
| NNW | 326.26–348.75 |
Life Index Keys
| Key | Scale | Meaning |
|---|---|---|
ultraviolet | realtime: 0–11; daily: 1–5 | UV index, from none to extreme |
dressing | 0–8 | Dressing recommendation, from very hot to extremely cold |
comfort | 0–13 | Comfort index, from muggy to dry cold |
coldRisk | 1–4 | Cold risk, from low chance to very high chance |
carWashing | 1–4 | Car washing suitability, from suitable to unsuitable |
Sources
Examples
Current Weather
Prompt:
查一下北京 116.3176,39.9760 现在的天气Command:
curl -s "https://api.caiyunapp.com/v2.6/${CAIYUN_WEATHER_API_TOKEN}/116.3176,39.9760/weather?hourlysteps=24&dailysteps=5&unit=metric:v2"Response style:
北京当前多云，气温 27C，体感 29C，湿度 68%。未来两小时天气平稳，24 小时内以多云到小雨为主。Next 2 Hours Rain
Prompt:
看看 121.4737,31.2304 未来两小时会不会下雨Command:
curl -s "https://api.caiyunapp.com/v2.6/${CAIYUN_WEATHER_API_TOKEN}/121.4737,31.2304/weather?hourlysteps=2&dailysteps=1&unit=metric:v2"Response style:
未来两小时重点提示：短时有小雨概率。优先参考 forecast_keypoint，其次再补充分钟级降水强度或概率。24-Hour Forecast
Prompt:
给我 114.0579,22.5431 未来 24 小时天气趋势Command:
curl -s "https://api.caiyunapp.com/v2.6/${CAIYUN_WEATHER_API_TOKEN}/114.0579,22.5431/weather?hourlysteps=24&dailysteps=3&unit=metric:v2"Response style:
未来 24 小时整体描述：白天多云，夜间有阵雨。回答时优先使用 hourly.description，再补充温度变化、降水和风力趋势。Daily Forecast
Prompt:
查 113.2644,23.1291 未来 5 天天气Command:
curl -s "https://api.caiyunapp.com/v2.6/${CAIYUN_WEATHER_API_TOKEN}/113.2644,23.1291/weather?hourlysteps=24&dailysteps=5&unit=metric:v2"Response style:
未来 5 天最高温 29-33C，最低温 22-26C，前两天多云，后续有阵雨。按天给出高低温、skycon 和必要的降水提示。Life Index
Prompt:
看下 104.0665,30.5728 的生活指数，重点说穿衣和紫外线Command:
curl -s "https://api.caiyunapp.com/v2.6/${CAIYUN_WEATHER_API_TOKEN}/104.0665,30.5728/weather?hourlysteps=24&dailysteps=5&unit=metric:v2"Response style:
先报告当前或近天的 life index 字段，再按 Field Reference 的等级说明解释 dressing、ultraviolet、comfort、coldRisk、carWashing。Weather Code Interpretation
Prompt:
返回里的 skycon 是 LIGHT_RAIN 和 CLOUDY，分别是什么意思Response style:
根据 Field Reference 解释 skycon 代码的含义，并在需要时补充降水强度阈值或天气现象优先级。Missing Coordinates
Prompt:
帮我查杭州天气Response style:
当前 skill 需要经纬度。先向用户索要 latitude 和 longitude，或者让用户提供一个已经解析好的坐标。Missing API Key
Prompt:
用 Caiyun Weather Skill 查 120.1551,30.2741 的天气Response style:
如果 CAIYUN_WEATHER_API_TOKEN 未设置且 ~/.config/caiyunapp/config.json 不存在，直接说明缺少凭据，并告诉用户设置环境变量或创建配置文件后再重试。