# Weather
> A complete weather intelligence library. Current conditions, forecasts, earthquakes, volcanoes, air quality, marine conditions, solar radiation, and historical climate — all from one endpoint set. Plus a natural-language AI reasoning endpoint for cross-domain synthesis.

Weather + nature intelligence behind x402 micropayments. Eight self-serve GET endpoints return precise, structured data from parallel upstream providers (Open-Meteo ECMWF, 7Timer NOAA GFS, NWS, Met Norway, WeatherAPI, OpenWeatherMap for weather; four FDSN seismic portals for earthquakes; NASA EONET for volcanoes — fastest source wins for redundancy and speed). A ninth endpoint, POST /weather/ask, asks a natural-language question and returns a synthesised, cross-validated answer using DeepSeek reasoning over the live feeds.

## Pricing
- `basic` tier — **$0.006125** on Base: `/weather/current`, `/weather/forecast`, `/nature/earthquakes`, `/nature/volcanoes`, `/nature/air-quality`, `/nature/marine`, `/nature/solar`, `/climate/historical`
- `regular` tier — **$0.056125** on Base: `/weather/ask`
- Chains: Base, Arbitrum, Polygon, Avalanche. Per-chain prices in `/.well-known/x402.json`.

## Operations
### data
- **GET /weather/current** — Current weather conditions for any location — temperature, humidity, wind. — params: `latitude` (number)*, `longitude` (number)* (tier: `basic`)
- **GET /weather/forecast** — 7-day weather forecast — daily highs, lows, precipitation. — params: `latitude` (number)*, `longitude` (number)*, `days` (integer) (tier: `basic`)
- **GET /nature/earthquakes** — Recent earthquake activity near a location — queries multiple seismic monitoring portals in parallel. Magnitude, depth, and distance. — params: `latitude` (number)*, `longitude` (number)*, `radius_km` (integer), `min_magnitude` (number) (tier: `basic`)
- **GET /nature/volcanoes** — Recent volcanic activity near a location — global volcano event monitoring. — params: `latitude` (number)*, `longitude` (number)*, `radius_km` (integer) (tier: `basic`)
- **GET /nature/air-quality** — Air quality index and pollutants at any location — European AQI, US AQI, PM2.5, PM10, ozone, and NO2. — params: `latitude` (number)*, `longitude` (number)* (tier: `basic`)
- **GET /nature/marine** — Marine conditions — wave height, sea surface temperature, swell height, and current velocity. — params: `latitude` (number)*, `longitude` (number)* (tier: `basic`)
- **GET /nature/solar** — Solar radiation data — shortwave and direct radiation, and sunshine duration. — params: `latitude` (number)*, `longitude` (number)* (tier: `basic`)
- **GET /climate/historical** — Historical weather data from 1940 to present — temperature, precipitation, and more. — params: `latitude` (number)*, `longitude` (number)*, `start_date` (string)*, `end_date` (string)* (tier: `basic`)

### inference
- **POST /weather/ask** — Premium multi-source intelligence: ask natural-language questions about weather, earthquakes, volcanoes, or natural events. Queries multiple weather models in parallel and returns the fastest result with cross-validation. — params: `question` (string)*, `latitude` (number), `longitude` (number) (tier: `regular`)

## Workflows
- **location_report** (Full weather + nature snapshot for one location): `current -> forecast -> air_quality` — Pull the three most common feeds together for a single place.
- **natural_event_brief** (Answer an open question about weather or natural hazards): `weather_ask` — Single-call AI reasoning over the live feeds.

## Data sources
- Open-Meteo (ECMWF models) — Primary forecast/current source.
- 7Timer (NOAA GFS models) — Independent weather source.
- NWS API (api.weather.gov) — US-only.
- Met Norway (api.met.no) — ECMWF via Norwegian Met.
- WeatherAPI.com (weather api) — Requires key (free tier).
- OpenWeatherMap (openweathermap) — Requires key (free tier).
- USGS FDSN (earthquake.usgs.gov)
- EMSC FDSN (seismicportal.eu)
- IRIS FDSN (service.iris.edu)
- GEOFON FDSN (geofon.gfz.de)
- NASA EONET (Smithsonian GVP) — Primary volcano source; USGS volcano fallback.

## Free endpoints
- GET `/`, `/health`, `/about`, `/.well-known/x402.json`, `/llms.txt`, `/openapi.json` (standard)
- GET `/weather/feedback` — Return the 50 most recent feedback entries
- POST `/weather/feedback` — Submit feedback (response_id, rating 1-5, optional comment)

## Examples
- `current` — Current conditions in London: `{"latitude": 51.5, "longitude": -0.12}`
- `weather_ask` — Ask about seismic activity near Tokyo: `{"question": "Is there any seismic or volcanic activity near Tokyo?", "latitude": 35.68, "longitude": 139.76}`