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)

Skycon Codes

Priority order: snow > rain > fog > sand > dust > haze > wind > cloudy > partly cloudy > clear.

Precipitation Intensity Thresholds

Wind Speed Scale (km/h)

Wind Direction (16-point)

Life Index Keys

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