# Skywatcher

> Global weather, set in type. Conditions, forecast, radar, alerts, air quality, and space weather for any place on Earth — served as public JSON APIs and a Vue 3 web client. No accounts, no auth, no tracking required.

Skywatcher runs on a single Cloudflare Worker that proxies and normalizes public weather sources, with KV caching at the edge. Every endpoint accepts `lat` and `lon` query parameters (decimal degrees, WGS84) and returns JSON. The web client is a single-page app served from the same Worker; pages can be deep-linked with `?lat=&lon=&name=` URL parameters.

## For agents (recommended path)

- [https://skywatcher.wtf/mcp](https://skywatcher.wtf/mcp): Remote MCP server (Model Context Protocol, Streamable HTTP, stateless). Add this URL to your MCP client (Claude Desktop, Claude Code, Cursor, etc.) and call tools directly. Available tools: `get_weather`, `get_forecast`, `get_hourly_forecast`, `get_alerts`, `get_air_quality`, `get_space_weather`, `search_locations`. Each accepts a single flexible `location` string ("Tokyo", "35.68,139.69", or empty for IP location).
- [https://skywatcher.wtf/openapi.json](https://skywatcher.wtf/openapi.json): OpenAPI 3.1 specification of the JSON APIs below. Drop this into a ChatGPT Custom GPT or any OpenAPI-aware client and you have a typed weather client.

## API endpoints

- [/api/weather?lat={lat}&lon={lon}](https://skywatcher.wtf/api/weather?lat=40.71&lon=-74.01): Current conditions, 24-hour hourly forecast, and 7-day daily forecast. Temperatures in °F, wind in mph. Uses Open-Meteo. 10-minute KV cache.
- [/api/alerts?lat={lat}&lon={lon}&cc={cc}](https://skywatcher.wtf/api/alerts?lat=40.71&lon=-74.01&cc=US): Active weather alerts. NWS for US locations, Meteoalarm for EU. Returns `{ alerts: [], region: 'us' | 'eu' | 'other' }`. 5–15 minute cache.
- [/api/air?lat={lat}&lon={lon}](https://skywatcher.wtf/api/air?lat=40.71&lon=-74.01): Air quality. Returns US AQI (preferred) or EU AQI, severity label, PM2.5, PM10, ozone, NO₂, SO₂, CO, plus 24-hour AQI sparkline and tree/grass/weed pollen levels where available. Open-Meteo source. 30-minute cache.
- [/api/space?lat={lat}](https://skywatcher.wtf/api/space?lat=40.71): Space weather aggregated from NOAA SWPC. Returns Kp index + trend, GOES X-ray flare class, solar wind speed + sparkline, aurora visibility chance computed from latitude, and active SWPC alerts. 10-minute cache.
- [/api/geocode?q={query}](https://skywatcher.wtf/api/geocode?q=Tokyo): Forward geocoding via Open-Meteo. Returns up to 5 candidate locations with name, admin1, country, lat/lon, timezone.
- [/api/iploc](https://skywatcher.wtf/api/iploc): Approximate location from the requester's IP via Cloudflare. Returns `{ lat, lon, name, countryCode, timezone, approximate: true }`. Used as fallback when geolocation is denied/unavailable.

## Deep links

- `https://skywatcher.wtf/?lat={lat}&lon={lon}&name={name}` — opens the SPA preloaded for that location. The Worker injects per-location `og:image`, `og:title`, `og:description`, and `twitter:card` meta tags via HTMLRewriter so social previews are accurate without JavaScript.
- `https://skywatcher.wtf/og?lat={lat}&lon={lon}&name={name}` — returns a 1200×630 PNG OpenGraph card with the location's current temperature and condition. Brand variant returned when no params are passed.

## Data sources

All public, no API keys required.

- Open-Meteo — current conditions, hourly + daily forecast, forward geocoding, air quality
- NWS (api.weather.gov) — US weather alerts (CAP)
- Meteoalarm — EU weather alerts (29 countries supported)
- NOAA SWPC — Kp index, GOES X-ray flux, solar wind plasma, active geomagnetic alerts
- RainViewer — radar tile manifest (client-side fetch)
- NASA SDO — solar corona imagery (193 Å, client-side)
- Cloudflare `request.cf` — IP geolocation

## Repository

- Source: [github.com/vajramatt/skywatcher.wtf](https://github.com/vajramatt/skywatcher.wtf)
- Stack: Cloudflare Workers (Hono) + Vue 3 + Vite + Leaflet + workers-og
- License: see repository

## Notes for agents

- All responses are JSON; no scraping required. Prefer the APIs above over parsing the HTML.
- Cache TTLs are listed per endpoint. Repeated requests within the TTL window return identical responses without re-fetching from upstreams.
- Latitude is clamped to two decimal places for cache-key normalization; clients passing more precision will hit the same cache bucket as their 2-dp neighbors.
- No rate limits are enforced by Skywatcher itself, but upstream sources (Open-Meteo, NWS, NOAA) have their own — please respect them by caching responses on your side.
- Outside the US and EU, `/api/alerts` returns `{ alerts: [], region: 'other' }` — silence is correct; do not synthesize alerts from other sources.