/alibabacloud-iqs-weather-query

name: alibabacloud-iqs-weather-query
description: |
  7-day weather forecast query powered by Alibaba Cloud IQS web search and page reading.
  Triggers: "weather forecast", "7-day weather", "weekly weather", "weather in [city]", "will it rain", "temperature forecast"

IQS Weather Query - 7-Day Weather Forecast

Query 7-day weather forecasts for any city using Alibaba Cloud IQS web search (UnifiedSearch) and page reading (ReadPageBasic) capabilities.

**Underlying Service:** [alibabacloud-iqs-search](https://skills.aliyun.com/skills/alibabacloud-iqs-search)

**Hybrid Parsing Strategy:**

• **Known sites** (weather.cma.cn, weather.com.cn): Dedicated parsers extract structured JSON → `parseMode: "structured"`
• **Unknown sites**: ReadPage extracts main content (readabilityMode: article), returns raw text with extraction hint → `parseMode: "raw"`, agent (LLM) interprets directly

| Output Field | Description | |--------------|-------------| | parseMode | `"structured"` (parsed JSON) or `"raw"` (text for agent) | | weather | Weather condition (sunny, cloudy, rain, etc.) | | temperature | Temperature range | | windSpeed | Wind speed/level | | windDirection | Wind direction |

---

Environment Configuration

> **Pre-check: ALIYUN_IQS_API_KEY Required** > > ```bash > if [ -z "$ALIYUN_IQS_API_KEY" ]; then echo "API Key 未配置"; else echo "API Key 已配置(已脱敏)"; fi > ``` > If output is 'API Key 未配置', the API Key is not configured. > > **How to obtain ALIYUN_IQS_API_KEY:** Please refer to [Aliyun IQS Documentation](https://help.aliyun.com/zh/document_detail/3025781.html) > > **Configure environment variable (choose one):** > > **Option 1: Temporary (current terminal session only)** > ```bash > export ALIYUN_IQS_API_KEY="your-api-key-here" > ``` > > **Option 2: Permanent (recommended)** > > Add to ~/.zshrc or ~/.bashrc: > ```bash > export ALIYUN_IQS_API_KEY="your-api-key-here" > ``` > Run `source ~/.zshrc` or `source ~/.bashrc` to apply. > > **Alternative:** Place API Key in `~/.alibabacloud/iqs/env` file: > ``` > ALIYUN_IQS_API_KEY=your-api-key-here > ```

---

Workflow

User Input (city name)
        │
        ▼
┌─────────────────────────┐
│ Step 1: UnifiedSearch    │  Search: "{city} 天气预报 未来7天"
│ (Web Search)            │  Priority: weather.cma.cn > weather.com.cn
└──────────┬──────────────┘
           │ Best weather URL
           ▼
┌─────────────────────────┐
│ Step 2: ReadPageBasic    │  Known site → readabilityMode: normal
│ (Page Reading)          │  Unknown site → readabilityMode: article
└──────────┬──────────────┘
           │ Page content
           ▼
     Known site?
      ╱        ╲
    YES          NO
     │            │
     ▼            ▼
  Parser       Return rawText
  Router       + hint for agent
     │         (parseMode: raw)
     ▼
  Structured JSON
  (parseMode: structured)

---

Usage

Prerequisites

• Node.js >= 18 (native `fetch` support required)
• No additional npm dependencies needed

Execute Query

node scripts/weather.mjs <city>

Examples:

node scripts/weather.mjs 北京
node scripts/weather.mjs 上海
node scripts/weather.mjs 杭州
node scripts/weather.mjs Tokyo

Output Format

**Structured mode** (known sites — parsed successfully):

{
  "success": true,
  "data": {
    "city": "北京",
    "parseMode": "structured",
    "queryTime": "2026-03-26T10:00:00.000Z",
    "forecastDays": 7,
    "forecast": [
      {
        "date": "3月26日",
        "weather": "晴",
        "temperature": "5°C ~ 18°C",
        "windDirection": "北风",
        "windSpeed": "3-4级"
      }
    ],
    "source": "https://weather.cma.cn/..."
  }
}

**Raw mode** (unknown sites — agent interprets the text):

{
  "success": true,
  "data": {
    "city": "北京",
    "parseMode": "raw",
    "hint": "以下是北京天气网页的正文内容，请从中提取未来7天的天气预报信息...",
    "rawText": "北京天气预报\n今天 晴 18°C/5°C ...",
    "evolveHint": "[持续进化] 当前站点 \"example.com\" 没有匹配的解析器...",
    "source": "https://example.com/weather/beijing"
  }
}

---

IQS APIs Used

| API | Endpoint | Purpose | Documentation | |-----|----------|---------|---------------| | UnifiedSearch | `cloud-iqs.aliyuncs.com/search/unified` | Web search for weather pages | [Doc](https://help.aliyun.com/zh/document_detail/2883041.html) | | ReadPageBasic | `cloud-iqs.aliyuncs.com/readpage/scrape` | Read and parse weather webpage | [Doc](https://help.aliyun.com/zh/document_detail/2983380.html) |

**Search Priority Sites (with dedicated parsers):** 1. weather.cma.cn (China Meteorological Administration) — `parseCmaWeather` → readabilityMode: `normal` 2. baidu.weather.com.cn / sq.weather.com.cn (China Weather Network mobile) — `parseBaiduWeatherComCn` → readabilityMode: `normal` 3. weather.com.cn (China Weather Network, all other subdomains) — `parseWeatherComCn` → readabilityMode: `normal` 4. Other sites — no parser, return raw text → readabilityMode: `article` (cleaner body extraction)

---

Error Handling

| Error Code | Description | Solution | |------------|-------------|----------| | CREDENTIALS_MISSING | API Key not configured | Set ALIYUN_IQS_API_KEY environment variable | | NO_RESULTS | No weather results found | Check city name is correct | | QUERY_FAILED | API call failed | Check network, verify credentials | | PARSE_FAILED | Failed to parse weather data from webpage | The target site's page structure may have changed; update the corresponding parser or add a new one (see Extending section) |

---

Best Practices

1. **Use Chinese city names** for domestic weather queries for better accuracy 2. **Node.js >= 18 required** - native `fetch` API is used, no npm install needed 3. **Cache awareness** - ReadPage uses `maxAge` not set, always fetches latest data 4. **Extensible parsers** - Each weather site has its own parser; add new sites by registering in `PARSER_REGISTRY`

---

Continuous Evolution

This skill is designed to **self-improve over time**. When the script encounters an unknown site format (no matc