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

1. Confirm coordinates are available.
2. 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.
3. 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"

4. 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
5. Return raw JSON only when the user asks for it.

Defaults

• Returned values are interpreted using metric:v2 units (see Field Reference below).
• Use hourlysteps=24 unless the user requests a different horizon.
• Use dailysteps=5 unless the user requests a different day count.

Failure Handling

• If credentials are missing, explain how to set CAIYUN_WEATHER_API_TOKEN or create ~/.config/caiyunapp/config.json with {"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}/weather

Supported 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 hours
• result.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 hours
• result.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 不存在，直接说明缺少凭据，并告诉用户设置环境变量或创建配置文件后再重试。