Free Hail Data API

Hail history for any US location, the individual NOAA ground reports behind it, and the cached radar swath overlays -- as JSON, over HTTPS, with no signup and no API key required.

What is in it

Two public sources, and nothing else. NOAA Storm Prediction Center ground reports (the archive starts 2010-01-01) drive the hail history and the report points. NOAA MRMS radar rasters drive the swath overlays.

No personal data is served by any endpoint here. There are no names, phone numbers, email addresses or street addresses in any response. SwathIQ's lead, export and admin endpoints are a separate authenticated surface and are deliberately absent from the OpenAPI document -- if it is not described there, it is not part of this API.

Endpoints

Endpoint	What it answers
GET /api/public/hail-history	Hail history near a point or a street address
GET /api/public/reports	SPC hail-report points for one date
GET /api/public/swath	Cached MRMS swath overlay for one date (metadata only)
GET /api/recent-storms	Storm days, newest first, with per-day counts
GET /api/legend	Hail-size colour scale used by the maps and rasters

Authentication and rate limits

Anonymous callers get 40 requests per 60 seconds per client IP on /api/public/*, enforced in-process. Over the ceiling the API answers 429 with a Retry-After header. A SwathIQ-issued bearer key is DOCUMENTED to raise that to 600 requests per 60 seconds, keyed on the key rather than on your IP. THAT TIER IS NOT LIVE YET: keys are not being issued, and sending an Authorization header today changes nothing -- the limiter deliberately ignores unvalidated credentials and meters you per IP. The ceiling is published here because it is the committed design (see docs/MCP-API-KEY-TIER.md), not because it is enforced. Ask for early access at https://swathiq.ccdocs.com/signup.

Nothing here needs a credential. A key, when the tier is live, only raises your rate-limit ceiling -- it grants no extra data and reaches no other endpoint. Ask for access if you need the higher ceiling.

Examples

Hail history near a street address, 5-mile radius, last 3 years:

curl -s 'https://swathiq.ccdocs.com/api/public/hail-history?address=123+Main+St&zip=75201&radius_miles=5&years=3'

The same query by coordinates (no geocoding, so no geocode hint in the reply):

curl -s 'https://swathiq.ccdocs.com/api/public/hail-history?lat=32.7876&lng=-96.7975&radius_miles=5'

Every SPC hail report point in Texas for one day:

curl -s 'https://swathiq.ccdocs.com/api/public/reports?date=2026-05-19&state=TX'

Where the cached swath overlay for a date lives, and its map bounds:

curl -s 'https://swathiq.ccdocs.com/api/public/swath?date=2026-05-19'

The last 30 days of storm days, largest hail first within each day:

curl -s 'https://swathiq.ccdocs.com/api/recent-storms?days=30&limit=50'

The hail-size colour scale the maps and rasters use:

curl -s 'https://swathiq.ccdocs.com/api/legend'

Three things that will bite you

• geocode: "zip_centroid" means the street was not matched. The result describes the middle of the ZIP, not the property, so a tight radius is meaningless. Check the hint before you trust the number.
• /api/public/swath never renders on demand. available: false means no raster is cached for that date -- it is NOT a statement that no hail fell. Rendering anonymously would download a radar file and burn CPU per request, which is a denial-of-service lever, so it is refused by design.
• /api/public/reports is capped at 5000 rows with no truncation flag. A count of exactly 5000 means you may be looking at a truncated day. Add state and page by state.

Attribution and fair use

The underlying observations are public NOAA data. If you publish figures derived from this API, cite NOAA SPC (reports) and NOAA MRMS (radar swaths); a link back to SwathIQ is appreciated but not required. Please keep to the published ceilings -- limits are enforced in-process and may be tightened without notice if the tier is abused.