# WittIoT Hyperlocal Weather Skill

## Description
Access real-time and historical hyperlocal weather data from WittIoT weather stations.
Supports 8 sensor types: temperature, humidity, pressure, light intensity, wind speed, wind gust, wind direction, and rainfall.

## Setup
1. Create an account at https://wittiot.com
2. Generate an API key at https://wittiot.com/index/apikey
3. Configure the API key in your AI agent settings

## Capabilities
- List user's weather stations
- Get real-time sensor readings (8 sensor types + derived values)
- Get historical data (24h, 7 days, 30 days)
- Query any public station by shortcode
- Unit conversion (°C/°F, m/s/mph/km·h/knots, hPa/inHg/mmHg, mm/in)

## Authentication
Pass your API key via `X-API-Key` header.

## API Endpoints
Base URL: https://wittiot.com

### Devices (requires auth)
- `GET /api/v1.Device/index` — List your weather stations
- `GET /api/v1.Device/read?id={id}` — Device details
- `GET /api/v1.Realtime/index?id={id}` — Current sensor readings
- `GET /api/v1.History/index?id={id}&range=24h` — Historical data (range: 24h, 7d, 30d)

### Public Data (no auth needed)
- `GET /api/v1.Shortcode/read?code={code}` — Query shortcode info
- `GET /api/v1.Shortcode/data?code={code}` — Get public station data

### User Management (requires auth)
- `GET /api/v1.User/settings` — Get user preferences
- `POST /api/v1.User/updateSettings` — Update units/timezone/language

## Sensors
| Sensor | Unit | Description |
|--------|------|-------------|
| temperature | °C | Air temperature, 0.01 precision |
| humidity | %RH | Relative humidity, 0.01 precision |
| pressure | hPa | Atmospheric pressure, 0.1 precision |
| light | Klux | Light intensity |
| wind_speed | m/s | Average wind speed |
| wind_gust | m/s | Maximum gust speed |
| wind_direction | ° | Wind direction 0-360 |
| rainfall | mm | Accumulated rainfall |

## Derived Values
| Value | Unit | Description |
|-------|------|-------------|
| dew_point | °C | Dew point temperature (Magnus formula) |
| feels_like | °C | Feels-like temperature (Heat Index / Wind Chill) |

## Example Interactions

**User**: "What's the temperature at my weather station?"
→ `GET /api/v1.Device/index` → `GET /api/v1.Realtime/index?id={id}` → Extract temperature

**User**: "Show me the weather trend for the past week"
→ `GET /api/v1.History/index?id={id}&range=7d` → Summarize trends

**User**: "What's the weather at station XT7K9P?"
→ `GET /api/v1.Shortcode/data?code=XT7K9P` → Format and present

**User**: "Is it going to rain? What's the pressure trend?"
→ `GET /api/v1.History/index?id={id}&range=24h` → Analyze pressure trend → Provide forecast hint

## Response Format
All responses follow: `{"code": 200, "msg": "ok", "data": {...}}`

## Rate Limits
- Authenticated: 100 requests/minute
- Public endpoints: 30 requests/minute