# fstwthr — long-form for AI agents

This document is the canonical long-form description of fstwthr for
LLMs and agents that want to ingest the whole site into a single
context window. The short version is at /llms.txt.

## What fstwthr is

fstwthr is a plain-text-first weather site at fstwthr.com. It serves
weather data through a unified canonical `Forecast` type, rendered
in seven formats (modern HTML, minimal HTML, plain text, JSON, YAML,
one-liner text, and MCP). It uses only free, keyless, government data
sources: NOAA in the US and MET Norway globally.

## Architecture

- Deployed on Cloudflare Workers.
- Multi-tier slug resolution: hand-curated cities → US Census places
  (~15.7k) → US Census ZIP codes (~33.8k ZCTAs) → KV-cached OSM
  Nominatim → live Nominatim.
- Provider router: US locations route to NOAA, everywhere else to
  MET Norway. Same canonical Forecast type comes out either way.
- Edge response cache (5-min fresh + 1-hour SWR) + KV upstream cache.
- Radar nowcast pipeline (US-only): a sibling Container fetches MRMS
  PrecipFlag every 5 min and writes per-gridpoint "rain on radar"
  records to KV, surfaced as a one-sentence clause in the summary.

## Canonical Forecast type

Every endpoint returns (or is rendered from) the same shape:

```
Forecast {
  location: { name, region, country, lat, lon, tz }
  observed: {
    temp, feels, dewpoint, condition, conditionText,
    wind: { speed, dir }, humidity, pressure, ts
  }
  hourly: [{ ts, temp, condition, conditionText, precipPct }]
  daily:  [{
    date, hi, lo, condition, conditionText, precipPct,
    sunrise, sunset, moonPhase: { fraction, illumination, name }
  }]
  alerts: [{ severity, headline, expires }]
  source: 'noaa' | 'metno' | …
  fetchedAt: ISO 8601
  yesterday?: { date, hi, lo } | null   // optional, when known
  periods?: NamedPeriod[]               // NOAA day/night narrative periods
  nowcast?: { type: 'rain'|'snow'|'mix'|'none', ts } | null
}
```

Units in the canonical type are imperial (°F, mph, inHg) — NOAA-native.
The render boundary converts to metric when `?units=metric` is set.

## How to use as an agent

1. **For most queries**: use the MCP server at https://mcp.fstwthr.com/mcp
   and call get_weather or get_best_window. Cleanest tool surface.
2. **For one-shot fetches**: curl https://json.fstwthr.com/{slug}
   returns the canonical Forecast as JSON.
3. **For inline summary**: curl https://fstwthr.com/{slug} returns
   plain text with a 1–3 sentence natural-language summary.

## Supported locations

### US
- All 50 states + DC, plus PR/VI/GU/MP/AS territories.
- City lookups via /<slug> for hand-curated set or any of the 15.7k
  Census places.
- ZIP code lookups via /<5-digit-zip> for any of the 33.8k US ZCTAs.

### International
- Hand-curated 40+ globally famous cities (London, Paris, Tokyo,
  Sydney, Berlin, Madrid, Mumbai, Mexico City, …).
- Long tail via OSM Nominatim; results KV-cached for 30 days.
- 45+ country → IANA timezone defaults built in.

## Attribution

- NOAA / National Weather Service (US data).
- MET Norway / Norwegian Meteorological Institute (global data).
- OpenStreetMap Foundation / Nominatim (geocoding long tail).
- US Census Bureau Gazetteer (place + ZIP data).

Data is free for non-commercial use under each provider's terms. See
each upstream's license for commercial considerations.

## Contact

For issues, questions, or peering interest: open an issue at
https://github.com/RJFerguson/fstwthr/issues.

## See also

- https://fstwthr.com/about — human-readable landing page.
- https://fstwthr.com/llms.txt — short LLM index.