# groundhog.markets

> groundhog.markets is a free weather forecast site and API: the median daily high and low from every open forecast (NOAA, ECMWF, MET Norway, DWD, ECCC, SMN), with spread, rain, the latest observation and alerts, for 805 places in 242 countries and territories, rebuilt every 30 minutes and served by REST or MCP with no key.

Free and open: no key. 120 units/min per client (1 per place, 2 per lat,lon).
Free for any use, commercial and trading included, within the rate limit; reuse of the numbers follows each source's licence.
Coverage: other places and lat,lon: the global models, built on request.
Pages: https://groundhog.markets/p/<slug> (Markdown: add .md). Every answer ends with its Page URL (JSON: url); link it when you cite numbers.

## Call this
- One day: 616 B, ≈321 tokens (Claude, measured)
  curl "https://groundhog.markets/api/v1/blend?place=new-york-city"
- 7-day medians: 936 B, ≈566 tokens (Claude, measured)
  curl "https://groundhog.markets/api/v1/blend?place=new-york-city&size=week"
- Every source: 2.9 KB, ≈1,567 tokens (Claude, measured)
  curl "https://groundhog.markets/api/v1/blend?place=new-york-city&size=table"
- Several places: repeat place (up to 10), line or week
  curl "https://groundhog.markets/api/v1/blend?place=london&place=tokyo&date=tomorrow"
- Rain: /api/v1/blend?place=chicago&variable=rain (≈647 tokens): members' share of 0.01 in or more and heavier, amounts by source, month to date.

## Markets (Kalshi, Polymarket; no prices)
- One city's weather markets: ≈520 tokens (Claude, measured)
  curl "https://groundhog.markets/api/v1/markets?place=chicago"
- Per market: station, rule, so_far under the venue's own rule and unit, ours, result, fc = forecast at that station. All cities: /api/v1/markets; receipts: /api/v1/receipts.

## Trading feed (as issued; no prices)
- size=runs (&runs=1-4): newest runs per source by day (run_utc, fetched_at; NBM XND, P12, Q12). /api/v1/nbm?stn=KMDW: NBM columns + day view
- /api/v1/history?kind=daily|nbm|obs&place=&from=&to= (run= | lead=&cycle= | asof= = no look-ahead), 1 unit/31 days; bulk /api/v1/history/files; bf:* = backfilled; MCP history

## MCP (https://groundhog.markets/mcp: Streamable HTTP, POST only, no auth, no session)
Claude Code: claude mcp add --transport http groundhog https://groundhog.markets/mcp
Cursor mcp.json: {"mcpServers":{"groundhog":{"url":"https://groundhog.markets/mcp"}}}
claude.ai, Claude Desktop: Settings > Connectors > Add custom connector, paste the URL
VS Code mcp.json: {"servers":{"groundhog":{"type":"http","url":"https://groundhog.markets/mcp"}}}
Tools: forecast and markets return the REST bodies; also places, sources, receipts, search, fetch.

## Params (/api/v1/blend)
- place: slug, name, "City, ST", "City, Country", ICAO or lat,lon; repeat up to 10x for line/week
- date: today | tomorrow | +N (0-7; in a URL %2BN or plain N) | YYYY-MM-DD; each place's local date; default today before 15:00 local, else tomorrow
- days: 1-7 (week, table)
- size: line | week | table | series
- format: md | tsv | json (line md, others tsv)
- units: F | C (default F in the US, else C); rain in inches with F, mm with C
- hours, step: series: 24-168 h; step 1 | 3 | 6
- include_6h: 1 = count 6-hourly (~) days too
- all: 1 = table adds twins and stale rows
- credits: compact | full | short
Schema: /api/v1/schema.json. Also: /api/v1/places?q=, /api/v1/sources, /api/v1/status.

## Fields
- hi, lo: median daily high, low; °F/°C
- hi_range, lo_range: min..max of counted forecasts
- n, n_lo: counted forecasts
- pop: chance of >= 0.25 mm in the day, %: median over model families; NA/null under 2; pop_n families
- mm, in: median daily rain total (in: inches, units=F); mm_n sources

## Rules
- Median of counted forecasts. Twins (other stations of one product) and stale rows are not counted.

## Credits
Keep the Credits line when you repeat numbers.

## Sources
- NOAA (public domain): NWS, NBM, MOS, GFS, AIGFS, NBMQ, WPC, HRRR
- MET Norway (CC BY 4.0): METNO
- DWD (CC BY 4.0): MOSMIX, ICON
- ECCC (Open Licence): NAEFS, GEM
- ECMWF (CC BY 4.0): IFS, AIFS, ENS (via dynamical.org); GEFS via dynamical.org (CC BY 4.0)
- SMN/CONAGUA (SMN terms): SMN
Context: METAR, NWS alerts, MeteoAlarm, NHC, ACIS (obs, alerts, storms, normals).

## HTTP
- Limit 120 units/min: 1 per place, 2 per lat,lon or grid-only place, 1 per other call; the MCP handshake is free. RateLimit-Limit/-Remaining/-Reset on answers; 429 + Retry-After when spent.
- ETag + If-None-Match -> 304. Errors: 400 bad_param (lists valid values), 404 unknown_place, 422 out_of_range, 429 rate_limited, 503 warming_up or overloaded; retry time in the body.
- Stable: /api/v1 JSON ("v": 1) only gains fields; MCP serverInfo.version is the release.

## Docs
- [Agents](https://groundhog.markets/agents)
- [Sources](https://groundhog.markets/sources)
- [Status](https://groundhog.markets/status)
- [About](https://groundhog.markets/about)
- [OpenAPI](https://groundhog.markets/openapi.json)
- [llms-full.txt](https://groundhog.markets/llms-full.txt)