### Comprehensive Weather Data Service Example

Source: https://context7.com/seniverse/seniverse-api/llms.txt

This example demonstrates how to create a Seniverse V3 client instance and fetch multiple types of weather data (current, daily, air quality, life suggestions) for a given city in parallel using Promise.all.

```APIDOC
## Comprehensive Weather Data Service Example

### Description
This example shows how to initialize the Seniverse V3 SDK client with custom configurations for encryption, caching, and query parameters. It then defines an asynchronous function `getCityWeatherInfo` that fetches current weather, 7-day forecast, air quality, and life suggestions for a specified city concurrently using `Promise.all`.

### Method
N/A (Client-side SDK usage)

### Endpoint
N/A (Client-side SDK usage)

### Parameters
N/A (Configuration is done during client initialization)

### Request Example
```typescript
import { SeniverseV3 } from 'seniverse-api'

// Client Initialization Configuration
const weatherService = new SeniverseV3({
  encryption: {
    uid: process.env.SENIVERSE_UID,
    key: process.env.SENIVERSE_KEY,
    ttl: 300,
    enabled: true
  },
  cache: {
    ttl: 'auto',
    max: 1000,
    enabled: true
  },
  query: {
    language: 'zh-Hans',
    unit: 'c',
    timeouts: [3000, 5000, 7000]
  },
  returnRaw: false
})

// Function to get weather info for a city
async function getCityWeatherInfo(city: string) {
  try {
    const [now, daily, air, suggestion] = await Promise.all([
      weatherService.weather.now.data({ location: city }),
      weatherService.weather.daily.data({ location: city, days: 7 }),
      weatherService.air.now.data({ location: city, scope: 'city' }),
      weatherService.life.suggestion.data({ location: city })
    ])

    return {
      city: now[0]?.location?.name,
      current: now[0]?.data[0],
      forecast: daily[0]?.data,
      airQuality: air[0]?.data[0],
      lifeIndex: suggestion[0]?.data[0],
      updateTime: now[0]?.last_update
    }
  } catch (error) {
    console.error('Error fetching weather data:', error)
    throw error
  }
}

// Usage Example
const beijingWeather = await getCityWeatherInfo('beijing')
console.log(`${beijingWeather.city} Weather:`, beijingWeather.current)
console.log('7-Day Forecast:', beijingWeather.forecast)
console.log('Air Quality:', beijingWeather.airQuality)
console.log('Life Index:', beijingWeather.lifeIndex)
```

### Response
#### Success Response (200)
Returns an object containing aggregated weather data:
- **city** (string) - The name of the city.
- **current** (object) - Current weather conditions.
- **forecast** (array) - Array of daily forecast data.
- **airQuality** (object) - Current air quality information.
- **lifeIndex** (object) - Life suggestion index.
- **updateTime** (string) - The timestamp of the last data update.

#### Response Example
```json
{
  "city": "Beijing",
  "current": {
    "obs_time": "2023-10-27T10:00:00+08:00",
    "temp": "15",
    "feels_like": "13",
    "humidity": "50",
    "wind_speed": "10",
    "wind_dir": "N",
    "wind_scale": "3",
    "pressure": "1010",
    "visibility": "10",
    "is_ ஈரப்பதமான": "0",
    "uv_index": "5",
    "sunrise": "06:30",
    "sunset": "17:45"
  },
  "forecast": [
    {
      "date": "2023-10-27",
      "high": "18",
      "low": "10",
      "avg_temp": "14",
      "day": {
        "text": "Sunny",
        "code": "00"
      },
      "night": {
        "text": "Clear",
        "code": "00"
      },
      "precip": "0",
      "wind_speed": "12",
      "wind_dir": "NE",
      "wind_scale": "3"
    }
    // ... more daily forecast data
  ],
  "airQuality": {
    "aqi": "50",
    "level": "1",
    "status": "Good",
    "primary": "PM2.5",
    "pm25": "20",
    "pm10": "30",
    "so2": "10",
    "no2": "15",
    "o3": "50",
    "co": "1"
  },
  "lifeIndex": {
    "dressing": {
      "brf": "Warm",
      "txt": "It is recommended to wear light clothing."
    },
    "flu": {
      "brf": "Low",
      "txt": "Low risk of catching a cold."
    },
    "uv": {
      "brf": "Moderate",
      "txt": "It is recommended to take sun protection measures."
    }
    // ... more life index data
  ],
  "updateTime": "2023-10-27T10:05:00+08:00"
}
```
```

--------------------------------

### Install Seniverse-API SDK

Source: https://github.com/seniverse/seniverse-api/blob/master/README.md

Install the package via npm to include it in your Node.js project dependencies.

```bash
npm i seniverse-api --save
```

--------------------------------

### Initialize SeniverseV3 Client in TypeScript

Source: https://context7.com/seniverse/seniverse-api/llms.txt

Demonstrates how to create an instance of the SeniverseV3 client with different configuration options, including API encryption, caching, and default query parameters. It shows both a full configuration and a minimal setup.

```typescript
import { SeniverseV3 } from 'seniverse-api'

// 完整配置示例
const seniverseV3 = new SeniverseV3({
  // API 加密/验证配置
  encryption: {
    uid: 'your-public-key',        // 公钥，从心知天气控制台获取
    key: 'your-private-key',       // 私钥，从心知天气控制台获取
    ttl: 300,                      // 签名有效期，单位秒
    enabled: true                  // 是否启用签名验证
  },
  // 内存缓存配置
  cache: {
    ttl: 'auto',                   // 缓存时间：数字(秒)或'auto'自动根据API设定
    max: 1000,                     // 最大缓存条数
    enabled: true                  // 是否启用缓存
  },
  // 默认请求参数
  query: {
    language: 'zh-Hans',           // 返回语言：zh-Hans/zh-Hant/en/ja等
    location: 'beijing',           // 默认地点
    unit: 'c',                     // 温度单位：c(摄氏)/f(华氏)
    timeouts: [3000, 5000, 7000]   // 重试超时时间(毫秒)，数组长度即重试次数
  },
  returnRaw: false                 // false返回统一格式，true返回API原始数据
})

// 最简配置（仅私钥，关闭签名验证）
const simpleClient = new SeniverseV3({
  encryption: {
    key: process.env.SENIVERSE_API_KEY,
    enabled: false
  }
})
```

--------------------------------

### Perform API Data Calls

Source: https://github.com/seniverse/seniverse-api/blob/master/README.md

Examples of fetching data using chainable methods mapped to API endpoints and using the request method for direct routing.

```javascript
import { SeniverseV3 } from 'seniverse-api'

const seniverseV3 = new SeniverseV3({ /* your config */ })

await seniverseV3.weather.now.data({ location: 'beijing', language: 'zh-Hans', unit: 'c' })
await seniverseV3.air.hourlyHistory.data({ location: 'beijing', language: 'zh-Hans', scope: 'city' })
await seniverseV3.life.chineseCalendar.data({ days: 2, start: 0 })

await seniverseV3.request('/weather/daily', { days: 2, start: -1, location: 'beijing' })
await seniverseV3.request('/air/hourly_history', { scope: 'city', location: 'beijing' })
```

--------------------------------

### Configure API Signature Verification (TypeScript)

Source: https://context7.com/seniverse/seniverse-api/llms.txt

This example demonstrates how to configure HMAC-SHA1 signature verification for enhanced API request security, recommended for production environments. It shows how to set up API keys, private keys, and signature validity periods, including using environment variables for configuration.

```typescript
import { SeniverseV3 } from 'seniverse-api'

// 启用签名验证
const clientWithAuth = new SeniverseV3({
  encryption: {
    uid: 'your-public-key',        // 从心知天气控制台获取
    key: 'your-private-key',       // 从心知天气控制台获取
    ttl: 300,                      // 签名有效期(秒)，建议300-1800
    enabled: true                  // 启用签名
  },
  query: {
    timeouts: [3000, 5000, 7000]
  }
})

// 使用环境变量配置（推荐）
const clientFromEnv = new SeniverseV3({
  encryption: {
    uid: process.env.SENIVERSE_UID,
    key: process.env.SENIVERSE_KEY,
    ttl: parseInt(process.env.SENIVERSE_TTL) || 300,
    enabled: true
  }
})

// 请求会自动附加签名参数: ts, sig, ttl, uid
const data = await clientWithAuth.weather.now.data({ location: 'beijing' })

// 仅使用 API Key（无签名验证）- 适用于测试环境
const clientSimple = new SeniverseV3({
  encryption: {
    key: 'your-api-key',
    enabled: false                 // 关闭签名，直接使用key
  }
})
```

--------------------------------

### GET /v3/weather/now

Source: https://github.com/seniverse/seniverse-api/blob/master/README.md

Retrieves current weather data for a specified location.

```APIDOC
## GET /v3/weather/now

### Description
Fetches the current weather conditions for a specific location.

### Method
GET

### Endpoint
/v3/weather/now.json

### Parameters
#### Query Parameters
- **location** (string) - Required - The location to query (e.g., 'beijing')
- **language** (string) - Optional - Language of the response (default: 'zh-Hans')
- **unit** (string) - Optional - Temperature unit (default: 'c')

### Request Example
```javascript
await seniverseV3.weather.now.data({ location: 'beijing' });
```

### Response
#### Success Response (200)
- **results** (array) - Weather data array

#### Response Example
{
  "results": [
    {
      "location": { "name": "Beijing", ... },
      "now": { "text": "Sunny", "temperature": "25" }
    }
  ]
}
```

--------------------------------

### GET /v3/weather/daily.json

Source: https://context7.com/seniverse/seniverse-api/llms.txt

Retrieves the weather forecast for multiple days.

```APIDOC
## GET /v3/weather/daily.json

### Description
Fetches daily weather forecast data for a specified number of days.

### Method
GET

### Endpoint
/v3/weather/daily.json

### Parameters
#### Query Parameters
- **location** (string) - Required - The city name or coordinates
- **days** (number) - Optional - Number of days to forecast
- **start** (number) - Optional - Start day offset

### Request Example
{
  "location": "shanghai",
  "days": 5
}

### Response
#### Success Response (200)
- **results** (array) - List of daily forecast data

#### Response Example
{
  "results": [{
    "daily": [{ "date": "2024-01-02", "text_day": "多云", "high": "28", "low": "20" }]
  }]
}
```

--------------------------------

### Generate JSONP Links

Source: https://github.com/seniverse/seniverse-api/blob/master/README.md

This section demonstrates how to generate JSONP links for making asynchronous calls to the Seniverse API. It includes examples for daily weather and hourly air quality data.

```APIDOC
## Generate JSONP Links

This section demonstrates how to generate JSONP links for making asynchronous calls to the Seniverse API. It includes examples for daily weather and hourly air quality data.

### Method
POST (Implicitly via `seniverse-api` library)

### Endpoint
`/weather/daily` and `/air/hourly` (relative paths used in the library)

### Parameters (for `seniverseV3.jsonp` method)
#### Query Parameters
- **callback** (string) - Required - The name of the JavaScript callback function to handle the response.
- **location** (string) - Required - The location for which to retrieve weather data (e.g., 'beijing').

#### Encryption Parameters (Optional, can be set during initialization)
- **ttl** (number) - Optional - Encryption expiration time in milliseconds.
- **uid** (string) - Optional - Public key for encryption.
- **key** (string) - Optional - Private key for encryption.

### Request Example (JavaScript)
```javascript
import { SeniverseV3 } from 'seniverse-api'

const seniverseV3 = new SeniverseV3({ /* your config */ })

// Generate JSONP link for daily weather
const url = seniverseV3.jsonp(
  '/weather/daily',
  {
    encryption: {
      ttl: 1000, 
      uid: '', 
      key: '', 
    },
    query: {
      callback: 'weatherDaily', 
      location: 'beijing' 
    }
  }
)

// Generate JSONP link for hourly air quality
seniverseV3.jsonp(
  '/air/hourly',
  {
    query: {
      callback: 'airHourly', 
      location: 'beijing' 
    }
  }
)
```

### Data Return Options

Control the data return format by setting the `returnRaw` option during `SeniverseV3` initialization:

1.  **`returnRaw: false` (Default)**:
    -   All interfaces return data in an array format.
    -   Data is extracted from the `results` field of the original API response.
    -   Specific data is encapsulated within a `data` array.
    -   Addresses inconsistencies in the original API response structure.

2.  **`returnRaw: true`**:
    -   Returns the raw data exactly as presented in the original API documentation, without any processing.
```

--------------------------------

### GET /v3/weather/now.json

Source: https://context7.com/seniverse/seniverse-api/llms.txt

Retrieves the current weather conditions for a specified location.

```APIDOC
## GET /v3/weather/now.json

### Description
Fetches current weather data including temperature, conditions, and last update time for a specific location.

### Method
GET

### Endpoint
/v3/weather/now.json

### Parameters
#### Query Parameters
- **location** (string) - Required - The city name or coordinates (e.g., 'beijing')

### Request Example
{
  "location": "beijing"
}

### Response
#### Success Response (200)
- **results** (array) - List of weather data objects

#### Response Example
{
  "results": [{
    "location": { "id": "WX4FBXXFKE4F", "name": "北京", "country": "CN" },
    "now": { "text": "晴", "code": "0", "temperature": "25" },
    "last_update": "2024-01-01T12:00:00+08:00"
  }]
}
```

--------------------------------

### GET /v3/air/now.json

Source: https://context7.com/seniverse/seniverse-api/llms.txt

Retrieves the current air quality index for a specified location.

```APIDOC
## GET /v3/air/now.json

### Description
Fetches real-time air quality data for a specific location.

### Method
GET

### Endpoint
/v3/air/now.json

### Parameters
#### Query Parameters
- **location** (string) - Required - The city name or coordinates
- **scope** (string) - Optional - Scope of data, e.g., 'city' or 'all'

### Request Example
{
  "location": "beijing",
  "scope": "city"
}

### Response
#### Success Response (200)
- **results** (array) - List of air quality data

#### Response Example
{
  "results": [{
    "air": { "city": { "aqi": "50", "pm25": "12", "quality": "优" } }
  }]
}
```

--------------------------------

### Initialize and Use Seniverse-API

Source: https://github.com/seniverse/seniverse-api/blob/master/README.md

Demonstrates how to initialize the SeniverseV3 client with encryption, cache, and query settings, and how to perform API calls using chainable methods or direct request routing.

```javascript
import { SeniverseV3 } from 'seniverse-api'

const seniverseV3 = new SeniverseV3({
  encryption: {
    uid: '',
    key: '',
    ttl: 10000,
    enabled: false
  },
  query: {
    unit: 'c',
    language: '',
    timeouts: [3000, 3000]
  },
  cache: {
    ttl: 100,
    max: 1000,
    enabled: true
  },
  returnRaw: false
})

await seniverseV3.weather.daily.data({ days: 2, start: -1, location: 'beijing' })
await seniverseV3.air.hourlyHistory.data({ scope: 'city', location: 'beijing' })

await seniverseV3.request('/weather/daily', { days: 2, start: -1, location: 'beijing' })

seniverseV3.jsonp('/weather/daily', {
  encryption: { ttl: 1000, uid: '', key: '' },
  query: { callback: 'weatherDaily', location: 'beijing' }
})
```

--------------------------------

### Implement Full Weather Service Integration with Seniverse SDK

Source: https://context7.com/seniverse/seniverse-api/llms.txt

This snippet demonstrates how to initialize the SeniverseV3 client with encryption and caching settings, and how to fetch aggregated weather data including current conditions, daily forecasts, air quality, and life suggestions using Promise.all for performance.

```typescript
import { SeniverseV3 } from 'seniverse-api';

const weatherService = new SeniverseV3({
  encryption: {
    uid: process.env.SENIVERSE_UID,
    key: process.env.SENIVERSE_KEY,
    ttl: 300,
    enabled: true
  },
  cache: {
    ttl: 'auto',
    max: 1000,
    enabled: true
  },
  query: {
    language: 'zh-Hans',
    unit: 'c',
    timeouts: [3000, 5000, 7000]
  },
  returnRaw: false
});

async function getCityWeatherInfo(city: string) {
  try {
    const [now, daily, air, suggestion] = await Promise.all([
      weatherService.weather.now.data({ location: city }),
      weatherService.weather.daily.data({ location: city, days: 7 }),
      weatherService.air.now.data({ location: city, scope: 'city' }),
      weatherService.life.suggestion.data({ location: city })
    ]);

    return {
      city: now[0]?.location?.name,
      current: now[0]?.data[0],
      forecast: daily[0]?.data,
      airQuality: air[0]?.data[0],
      lifeIndex: suggestion[0]?.data[0],
      updateTime: now[0]?.last_update
    };
  } catch (error) {
    console.error('获取天气数据失败:', error);
    throw error;
  }
}

const beijingWeather = await getCityWeatherInfo('beijing');
console.log(`${beijingWeather.city}天气:`, beijingWeather.current);
```

--------------------------------

### Configure Seniverse Client Instance

Source: https://github.com/seniverse/seniverse-api/blob/master/README.md

Detailed configuration object for the SeniverseV3 client, including memory caching, signature validation, and default query parameters.

```javascript
import { SeniverseV3 } from 'seniverse-api'

const seniverseV3 = new SeniverseV3({
  cache: {
    ttl: 100,
    max: 1000,
    enabled: true
  },
  encryption: {
    uid: '',
    key: '',
    ttl: 100,
    enabled: true
  },
  query: {
    language: 'zh-Hans',
    location: 'beijing',
    unit: 'c',
    timeouts: [3000, 5000, 7000]
  },
  returnRaw: false
})
```

--------------------------------

### Fetch Real-time and Forecast Weather Data (TypeScript)

Source: https://context7.com/seniverse/seniverse-api/llms.txt

This snippet demonstrates how to fetch real-time weather, daily forecasts, hourly forecasts, historical weather, weather alerts, and minute-level precipitation forecasts using the Seniverse Weather API. It requires a Seniverse V3 client with an API key and supports various parameters like location, language, units, and forecast duration.

```typescript
import { SeniverseV3 } from 'seniverse-api'

const client = new SeniverseV3({
  encryption: { key: 'your-api-key', enabled: false },
  cache: { enabled: true, ttl: 'auto', max: 1000 }
})

// 实时天气 weather.now
const now = await client.weather.now.data({
  location: 'beijing',      // 城市名/城市ID/IP/经纬度
  language: 'zh-Hans',      // 返回语言
  unit: 'c'                 // 温度单位
})
// 返回数据包含: text(天气状况), code(天气代码), temperature(温度)等

// 逐日天气预报 weather.daily
const daily = await client.weather.daily.data({
  location: 'beijing',
  days: 15,                 // 天数，最多15天
  start: 0                  // 起始日期，0=今天，-1=昨天
})

// 逐三小时天气预报 weather.hourly3h
const hourly3h = await client.weather.hourly3h.data({
  location: 'beijing',
  hours: 48
})

// 逐小时天气预报 weather.hourly
const hourly = await client.weather.hourly.data({
  location: 'beijing'
})

// 历史天气 weather.hourlyHistory
const history = await client.weather.hourlyHistory.data({
  location: 'beijing'
})

// 气象预警 weather.alarm
const alarm = await client.weather.alarm.data({
  location: 'beijing'
})

// 分钟级降水预报 weather.grid.minutely
const minutely = await client.weather.grid.minutely.data({
  location: '39.93:116.40'  // 经纬度格式
})
```

--------------------------------

### Generate JSONP Request URL with SeniverseV3

Source: https://github.com/seniverse/seniverse-api/blob/master/README.md

Demonstrates how to initialize the SeniverseV3 client and generate a JSONP URL for specific API endpoints. It shows how to pass encryption parameters and query strings, including the required callback function name.

```javascript
import { SeniverseV3 } from 'seniverse-api';

const seniverseV3 = new SeniverseV3({ /* your config */ });

// Generate JSONP URL for weather daily endpoint
const url = seniverseV3.jsonp(
  '/weather/daily',
  {
    encryption: {
      ttl: 1000,
      uid: '',
      key: '',
    },
    query: {
      callback: 'weatherDaily',
      location: 'beijing'
    }
  }
);

// Generate JSONP URL for air hourly endpoint
seniverseV3.jsonp(
  '/air/hourly',
  {
    query: {
      callback: 'airHourly',
      location: 'beijing'
    }
  }
);
```

--------------------------------

### Fetch Weather Data using Chained Calls in TypeScript

Source: https://context7.com/seniverse/seniverse-api/llms.txt

Illustrates how to retrieve various weather data points (real-time, daily forecast, hourly forecast) using the SDK's chained method calls. This approach maps directly to API endpoints and requires specifying parameters for each request.

```typescript
import { SeniverseV3 } from 'seniverse-api'

const client = new SeniverseV3({
  encryption: { key: 'your-api-key', enabled: false },
  cache: { enabled: true, ttl: 'auto', max: 1000 },
  query: { language: 'zh-Hans', unit: 'c', timeouts: [3000, 5000] }
})

// 获取实时天气 - 对应 /v3/weather/now.json
const weatherNow = await client.weather.now.data({
  location: 'beijing'
})
// 返回: [{ location: {...}, data: [{...}], last_update: "2024-01-01T12:00:00+08:00" }]

// 获取未来多日天气预报 - 对应 /v3/weather/daily.json
const weatherDaily = await client.weather.daily.data({
  location: 'shanghai',
  days: 5,
  start: 0
})

// 获取逐小时天气预报 - 对应 /v3/weather/hourly.json
const weatherHourly = await client.weather.hourly.data({
  location: 'guangzhou',
  hours: 24
})

// 获取实时空气质量 - 对应 /v3/air/now.json
const airNow = await client.air.now.data({
  location: 'beijing',
  scope: 'city'  // city/all
})

// 获取空气质量预报 - 对应 /v3/air/daily.json
const airDaily = await client.air.daily.data({
  location: 'beijing',
  days: 5
})

// 获取历史空气质量 - 对应 /v3/air/hourly_history.json
const airHistory = await client.air.hourlyHistory.data({
  location: 'beijing',
  scope: 'city'
})
```

--------------------------------

### Fetch Data using Path Calls in TypeScript

Source: https://context7.com/seniverse/seniverse-api/llms.txt

Demonstrates fetching various data types (weather, air quality, life suggestions, calendar, sun times) by directly specifying the API path and parameters using the `request` method. This method is suitable for users familiar with the raw API structure.

```typescript
import { SeniverseV3 } from 'seniverse-api'

const client = new SeniverseV3({
  encryption: { key: 'your-api-key', enabled: false },
  query: { language: 'zh-Hans', unit: 'c', timeouts: [3000, 5000] }
})

// 获取天气预报
const dailyWeather = await client.request('/weather/daily', {
  location: 'beijing',
  days: 3,
  start: 0
})

// 获取实时天气
const nowWeather = await client.request('/weather/now', {
  location: 'shanghai'
})

// 获取气象预警
const weatherAlarm = await client.request('/weather/alarm', {
  location: 'guangzhou'
})

// 获取空气质量历史数据
const airHistory = await client.request('/air/hourly_history', {
  location: 'beijing',
  scope: 'city'
})

// 获取生活指数建议
const lifeSuggestion = await client.request('/life/suggestion', {
  location: 'beijing'
})

// 获取农历信息
const chineseCalendar = await client.request('/life/chinese_calendar', {
  days: 7,
  start: 0
})

// 获取日出日落时间
const sunTimes = await client.request('/geo/sun', {
  location: 'beijing',
  days: 3
})
```

--------------------------------

### Handle API Data Return Formats (TypeScript)

Source: https://context7.com/seniverse/seniverse-api/llms.txt

This section explains how to manage the data formats returned by the Seniverse API SDK. It shows how to switch between a unified SDK format (default) and the raw API format by setting the `returnRaw` option. This is useful for simplifying data processing or when direct access to the API's original response is needed.

```typescript
import { SeniverseV3 } from 'seniverse-api'

// returnRaw: false (默认) - 统一格式
const clientFormatted = new SeniverseV3({
  encryption: { key: 'your-api-key', enabled: false },
  returnRaw: false
})

const formattedResult = await clientFormatted.weather.daily.data({
  location: 'beijing',
  days: 3
})
// 返回格式:
// [{
//   location: { id: "WX4FBXXFKE4F", name: "北京", ... },
//   data: [
//     { date: "2024-01-01", text_day: "晴", high: "5", low: "-3", ... },
//     { date: "2024-01-02", text_day: "多云", high: "3", low: "-5", ... }
//   ],
//   last_update: "2024-01-01T08:00:00+08:00"
// }]

// returnRaw: true - API 原始格式
const clientRaw = new SeniverseV3({
  encryption: { key: 'your-api-key', enabled: false },
  returnRaw: true
})

const rawResult = await clientRaw.weather.daily.data({
  location: 'beijing',
  days: 3
})
// 返回格式 (与API文档一致):
// {
//   results: [{
//     location: { id: "WX4FBXXFKE4F", name: "北京", ... },
//     daily: [
//       { date: "2024-01-01", text_day: "晴", ... },
//       { date: "2024-01-02", text_day: "多云", ... }
//     ],
//     last_update: "2024-01-01T08:00:00+08:00"
//   }]
// }
```

--------------------------------

### Configure and Use Caching Mechanisms (TypeScript)

Source: https://context7.com/seniverse/seniverse-api/llms.txt

This code illustrates how to leverage the SDK's built-in LRU caching to reduce API request latency and costs. It covers automatic TTL settings based on API data freshness, manual TTL configuration, and disabling the cache entirely for scenarios requiring real-time data.

```typescript
import { SeniverseV3 } from 'seniverse-api'

// 开启智能缓存 - 自动根据API特性设置缓存时间
const clientAutoCache = new SeniverseV3({
  encryption: { key: 'your-api-key', enabled: false },
  cache: {
    ttl: 'auto',            // 自动设置: 实时数据约10分钟，预报数据约1小时
    max: 1000,              // 最多缓存1000条记录
    enabled: true
  }
})

// 首次请求 - 从API获取
const result1 = await clientAutoCache.weather.daily.data({ location: 'beijing' })

// 再次请求 - 命中缓存，无网络请求
const result2 = await clientAutoCache.weather.daily.data({ location: 'beijing' })

// 不同参数 - 缓存未命中，从API获取
const result3 = await clientAutoCache.weather.daily.data({ location: 'shanghai' })

// 固定缓存时间
const clientFixedCache = new SeniverseV3({
  encryption: { key: 'your-api-key', enabled: false },
  cache: {
    ttl: 300,               // 所有数据缓存5分钟
    max: 500,
    enabled: true
  }
})

// 关闭缓存 - 适用于数据时效性要求极高的场景
const clientNoCache = new SeniverseV3({
  encryption: { key: 'your-api-key', enabled: false },
  cache: {
    enabled: false
  }
})
```

--------------------------------

### Access Professional Grid Weather and Soil Data (TypeScript)

Source: https://context7.com/seniverse/seniverse-api/llms.txt

This snippet shows how to use the Seniverse Professional API to fetch high-precision grid-level meteorological data, including real-time grid weather, 3-hour forecasts, historical grid weather, and soil moisture/temperature data. This API typically requires signature verification with a UID and API key.

```typescript
import { SeniverseV3 } from 'seniverse-api'

const client = new SeniverseV3({
  encryption: {
    uid: 'your-uid',
    key: 'your-api-key',
    ttl: 300,
    enabled: true           // 专业版通常需要签名验证
  }
})

// 格点实时天气 pro.weather.grid.now
const gridNow = await client.pro.weather.grid.now.data({
  location: '39.93:116.40'  // 经纬度格式
})

// 格点逐三小时预报 pro.weather.grid.hourly3h
const gridHourly = await client.pro.weather.grid.hourly3h.data({
  location: '39.93:116.40'
})

// 格点历史天气 pro.weather.grid.hourlyHistory
const gridHistory = await client.pro.weather.grid.hourlyHistory.data({
  location: '39.93:116.40'
})

// 土壤湿度数据 pro.soil.grid.now
const soilData = await client.pro.soil.grid.now.data({
  location: '39.93:116.40'
})
// 返回: 土壤湿度、土壤温度等农业相关数据
```

--------------------------------

### Interact with Robot Chat API for Weather Queries (TypeScript)

Source: https://context7.com/seniverse/seniverse-api/llms.txt

This snippet demonstrates how to use the Seniverse API SDK to query weather information through a natural language interface. It supports integration with chatbots and voice assistants. The input is a user's query, and the output is a natural language response.

```typescript
import { SeniverseV3 } from 'seniverse-api'

const client = new SeniverseV3({
  encryption: { key: 'your-api-key', enabled: false }
})

// 天气对话 robot.talk
const response = await client.robot.talk.data({
  q: '北京今天天气怎么样',
  location: 'beijing'
})
// 返回: 自然语言回复，如"北京今天晴，气温15-25度，适宜外出"
```

--------------------------------

### Fetch Air Quality Data (TypeScript)

Source: https://context7.com/seniverse/seniverse-api/llms.txt

This snippet shows how to retrieve real-time and forecast air quality data, including AQI and pollutant levels, for cities and monitoring stations. It also covers air quality rankings and historical data. The Seniverse Air Quality API requires a client with an API key.

```typescript
import { SeniverseV3 } from 'seniverse-api'

const client = new SeniverseV3({
  encryption: { key: 'your-api-key', enabled: false },
  cache: { enabled: true, ttl: 60 * 10, max: 500 }
})

// 实时空气质量 air.now
const airNow = await client.air.now.data({
  location: 'beijing',
  scope: 'city'             // city=城市级, all=含监测站
})
// 返回: AQI, PM2.5, PM10, SO2, NO2, O3, CO, 首要污染物, 质量等级

// 逐日空气质量预报 air.daily
const airDaily = await client.air.daily.data({
  location: 'beijing',
  days: 5
})

// 逐小时空气质量 air.hourly
const airHourly = await client.air.hourly.data({
  location: 'beijing'
})

// 历史空气质量 air.hourlyHistory
const airHistory = await client.air.hourlyHistory.data({
  location: 'beijing',
  scope: 'city'
})

// 空气质量城市排名 air.ranking
const ranking = await client.air.ranking.data({})
// 返回全国城市空气质量排名

// AQI 预报 aqi.daily
const aqiDaily = await client.aqi.daily.data({
  location: 'beijing',
  days: 5
})

// AQI 逐小时 aqi.hourly
const aqiHourly = await client.aqi.hourly.data({
  location: 'beijing'
})
```

--------------------------------

### Query Location and Astronomical Data (TypeScript)

Source: https://context7.com/seniverse/seniverse-api/llms.txt

This snippet illustrates how to use the Seniverse API to search for cities and locations, and to retrieve astronomical data such as sunrise and sunset times, and moonrise and moonset times. It requires a Seniverse V3 client with an API key.

```typescript
import { SeniverseV3 } from 'seniverse-api'

const client = new SeniverseV3({
  encryption: { key: 'your-api-key', enabled: false }
})

// 城市搜索 location.search
const cities = await client.location.search.data({
  q: '北京'                  // 搜索关键词
})
// 返回: 匹配的城市列表及其ID、经纬度等

// 日出日落时间 geo.sun
const sunTimes = await client.geo.sun.data({
  location: 'beijing',
  days: 7,
  start: 0
})
// 返回: 日出时间、日落时间

// 月升月落时间 geo.moon
const moonTimes = await client.geo.moon.data({
  location: 'beijing',
  days: 7,
  start: 0
})
// 返回: 月升时间、月落时间、月相
```

--------------------------------

### Fetch Marine Tide and Grid Forecast Data (TypeScript)

Source: https://context7.com/seniverse/seniverse-api/llms.txt

This snippet demonstrates how to access marine tide forecasts for coastal ports and ocean grid forecasts, including wave height and sea temperature. It requires a Seniverse V3 client with an API key and uses port IDs or latitude/longitude for location.

```typescript
import { SeniverseV3 } from 'seniverse-api'

const client = new SeniverseV3({
  encryption: { key: 'your-api-key', enabled: false }
})

// 潮汐预报 tide.daily
const tide = await client.tide.daily.data({
  location: 'P2927',        // 港口ID
  days: 3
})
// 返回: 高潮时间、低潮时间、潮高

// 海洋格点预报 ocean.grid.hourly
const oceanHourly = await client.ocean.grid.hourly.data({
  location: '31.23:121.47'  // 经纬度
})
// 返回: 海浪、海温等数据
```

--------------------------------

### Access Life Index and Chinese Calendar Data (TypeScript)

Source: https://context7.com/seniverse/seniverse-api/llms.txt

This snippet demonstrates how to retrieve lifestyle suggestions (e.g., clothing, sports, car washing) and traditional Chinese calendar information, including festivals, solar terms, and auspicious/inauspicious days. It uses the Seniverse Life API and requires an API key.

```typescript
import { SeniverseV3 } from 'seniverse-api'

const client = new SeniverseV3({
  encryption: { key: 'your-api-key', enabled: false }
})

// 生活指数建议 life.suggestion
const suggestion = await client.life.suggestion.data({
  location: 'beijing'
})
// 返回: 穿衣、紫外线、洗车、旅游、感冒、运动等指数

// 农历节气 life.chineseCalendar
const calendar = await client.life.chineseCalendar.data({
  days: 30,                 // 查询天数
  start: 0                  // 起始日期
})
// 返回: 农历日期、节气、宜忌、生肖、干支等

// 限行信息 life.drivingRestriction
const restriction = await client.life.drivingRestriction.data({
  location: 'beijing'
})
// 返回: 限行尾号、限行时间等
```

--------------------------------

### Generate JSONP Call Links in TypeScript

Source: https://context7.com/seniverse/seniverse-api/llms.txt

Shows how to create signed JSONP URLs for direct API calls from a web browser. The `jsonp` method generates a URL with necessary signature parameters and a specified callback function, suitable for embedding in script tags.

```typescript
import { SeniverseV3 } from 'seniverse-api'

const client = new SeniverseV3({
  encryption: {
    uid: 'your-public-key',
    key: 'your-private-key',
    ttl: 300,
    enabled: true
  }
})

// 生成天气预报的 JSONP 链接
const weatherUrl = client.jsonp('/weather/daily', {
  query: {
    callback: 'handleWeatherData',  // JSONP 回调函数名
    location: 'beijing',
    days: 3
  }
})
// 返回: https://api.seniverse.com/v3/weather/daily.json?ts=...&sig=...&callback=handleWeatherData&location=beijing&days=3

// 生成空气质量的 JSONP 链接（覆盖加密配置）
const airUrl = client.jsonp('/air/now', {
  encryption: {
    uid: 'another-uid',
    key: 'another-key',
    ttl: 600
  },
  query: {
    callback: 'handleAirData',
    location: 'shanghai',
    scope: 'city'
  }
})

// 前端使用示例
// <script>
//   function handleWeatherData(data) {
//     console.log('天气数据:', data);
//   }
// </script>
// <script src="${weatherUrl}"></script>
```

--------------------------------

### Generic API Request

Source: https://github.com/seniverse/seniverse-api/blob/master/README.md

Generic method to call any Seniverse API endpoint using a route string.

```APIDOC
## GET /v3/[path]

### Description
Allows calling any Seniverse API endpoint by providing the path and query parameters directly.

### Method
GET

### Endpoint
/v3/{path}

### Parameters
#### Path Parameters
- **path** (string) - Required - The API route (e.g., '/weather/daily')

#### Query Parameters
- **params** (object) - Required - API specific query parameters

### Request Example
```javascript
await seniverseV3.request('/weather/daily', { days: 2, location: 'beijing' });
```

### Response
#### Success Response (200)
- **results** (object) - API response data

#### Response Example
{
  "results": { ... }
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.