npm package: @openpets/weather
Description: Multi-provider weather plugin with OpenWeatherMap, Visual Crossing, and WeatherAPI.com support for current conditions, forecasts, and location-based weather discovery
Latest version: 1.0.1

# Weather Plugin

Comprehensive weather plugin for OpenCode providing real-time weather data, forecasts, and location-based weather discovery using OpenWeatherMap API.

## Features

- **Current Weather**: Get real-time weather conditions for any location
- **Weather Forecasts**: 5-day weather forecasts with daily summaries
- **Tomorrow's Weather**: Quick access to tomorrow's weather conditions
- **Good Weather Finder**: Find locations with optimal weather conditions around a specific area
- **Multiple Location Formats**: Support for city names, coordinates, and zip codes
- **Flexible Units**: Metric, imperial, or kelvin temperature units

## Setup

### 1. Get OpenWeatherMap API Key

1. Visit [OpenWeatherMap](https://openweathermap.org/api)
2. Sign up for a free account
3. Get your API key (free tier includes 1000 calls/day)

### 2. Configure Environment

Create a `.env` file in weather plugin directory:

```bash
# Required: OpenWeatherMap API key
OPENWEATHER_API_KEY=your_api_key_here

# Optional: Temperature units (metric, imperial, kelvin)
# Default: metric
WEATHER_UNITS=metric
```

### 3. Test Plugin

```bash
# Test connection
opencode run "test weather connection"

# Get current weather
opencode run "get current weather in New York"

# Get tomorrow's forecast
opencode run "get weather forecast for tomorrow in London"

# Find good weather locations
opencode run "find good weather places near Athens, Greece"
```

## Available Tools

### weather-test-connection
Test plugin connection and configuration status.

```bash
opencode run "test weather connection"
```

### weather-get-current
Get current weather conditions for a location.

**Parameters:**
- `location` (required): City name, coordinates (lat,lon), or zip code
- `units` (optional): Temperature units (metric, imperial, kelvin)

**Examples:**
```bash
opencode run "get current weather in Tokyo"
opencode run "get current weather for 40.7128,-74.0060"
opencode run "get current weather in Paris with imperial units"
```

### weather-get-forecast
Get weather forecast for a location.

**Parameters:**
- `location` (required): City name, coordinates, or zip code
- `days` (optional): Number of days to forecast (1-5, default: 5)
- `units` (optional): Temperature units

**Examples:**
```bash
opencode run "get weather forecast for Berlin"
opencode run "get 3 day forecast for Madrid"
opencode run "get weather forecast for Sydney with metric units"
```

### weather-get-tomorrow
Get tomorrow's weather forecast for a location.

**Parameters:**
- `location` (required): City name, coordinates, or zip code
- `units` (optional): Temperature units

**Examples:**
```bash
opencode run "get weather forecast for tomorrow in Rome"
opencode run "what's the weather like tomorrow in Amsterdam"
```

### weather-find-good-places
Find locations with good weather conditions around a specific area.

**Parameters:**
- `location` (required): Center location (city name or coordinates)
- `radius` (optional): Search radius in km (10-500, default: 100)
- `day` (optional): Day to check (today, tomorrow, default: tomorrow)
- `min_temp` (optional): Minimum temperature (default: 15°C)
- `max_temp` (optional): Maximum temperature (default: 30°C)
- `units` (optional): Temperature units

**Examples:**
```bash
opencode run "find good weather places near Athens, Greece"
opencode run "find good weather locations within 50km of Barcelona"
opencode run "find warm weather places near Miami for tomorrow"
```

## Good Weather Criteria

The "good weather" assessment considers:

- **Temperature**: 15-30°C (59-86°F) - comfortable range
- **Conditions**: No rain, snow, thunderstorm, or drizzle
- **Humidity**: Below 80% - not too humid
- **Wind**: Below 25 km/h - not too windy

Each location receives a score (0-4) based on how many criteria it meets.

## Response Format

All tools return structured JSON responses:

```json
{
  "success": true,
  "location": {
    "name": "London",
    "country": "GB"
  },
  "current": {
    "temperature": 18,
    "feels_like": 17,
    "humidity": 65,
    "pressure": 1013
  },
  "weather": {
    "main": "Clouds",
    "description": "partly cloudy"
  },
  "units": "metric"
}
```

## Error Handling

The plugin provides clear error messages for:

- Missing API keys
- Invalid locations
- API rate limits
- Network issues

## Usage Examples

### Travel Planning
```bash
# Check current weather at destination
opencode run "get current weather in Athens, Greece"

# Check tomorrow's forecast
opencode run "get weather forecast for tomorrow in Athens, Greece"

# Find better weather nearby if needed
opencode run "find good weather places near Athens, Greece"
```

### Daily Weather Check
```bash
# Quick current weather
opencode run "get current weather in my location"

# Plan for tomorrow
opencode run "get weather forecast for tomorrow"
```

### Event Planning
```bash
# Check weekend forecast
opencode run "get 3 day forecast for wedding location"

# Find backup venues with good weather
opencode run "find good weather places near event venue"
```

## Rate Limits

- **Free Tier**: 1000 API calls per day
- **Pro Tier**: 100,000 API calls per day
- Each tool call uses 1 API credit
- The "find good places" tool uses multiple API calls (8-12 per search)

## Tips

1. **Use coordinates for precision**: `40.7128,-74.0060` is more accurate than "New York"
2. **Check forecasts first**: Before searching for good weather places
3. **Adjust temperature ranges**: Use custom min/max temp for your preferences
4. **Monitor usage**: Track API calls to avoid hitting limits

## Troubleshooting

### "Invalid API key" error
- Verify your API key is correct
- Check if key is activated (may take a few hours after registration)
- Ensure no extra spaces or characters in .env file

### "Location not found" error
- Try alternative spellings or formats
- Use coordinates for better accuracy
- Check if the location exists in OpenWeatherMap's database

### Rate limit errors
- Upgrade to a paid plan for higher limits
- Implement caching in your application
- Use forecast data instead of multiple current weather calls

## Data Sources

- **Provider**: OpenWeatherMap
- **API**: Current Weather Data & 5 Day Weather Forecast
- **Update Frequency**: Every 10 minutes for current weather
- **Forecast Accuracy**: Typically 80-90% for 1-3 day forecasts

## Support

For issues with:
- **API Keys**: Contact OpenWeatherMap support
- **Plugin Issues**: Check OpenPets documentation
- **Feature Requests**: Submit an issue to the OpenPets repository