{"openapi":"3.0.3","info":{"title":"Satinwood — US Property Catastrophe Risk API","version":"3.0.0","description":"Property-level multi-peril catastrophe risk for the United States — **flood, wind, wildfire & earthquake**. Every profile returns an **overall** score plus the peril blocks:\n\n- **Flood** (FEMA-zone-anchored) → coastal / fluvial / pluvial sub-scores. Uses FEMA NFHL zones, **HAND** (height above nearest drainage), and **freeboard** (elevation − Base Flood Elevation).\n- **Wind** (insurance-grade) → hurricane / tornado / strong-wind sub-scores from **observed event climatology** — NOAA **HURDAT2** hurricane best-tracks (intensity + dwell, annualized) and NOAA **SPC** tornado tracks (EF-weighted), plus **WBDR** and **NCIUA Beach-Plan** overlays.\n- **Wildfire** (insurance-grade) → **USFS Wildfire Hazard Potential** — physical fuel/burn-probability hazard, demographics-free (dominant class + worst-pocket escalation).\n- **Earthquake** (insurance-grade) → **USGS 2%-in-50-yr Peak Ground Acceleration** ground-shaking contours.\n\nOverall is a weighted-max across all four perils (0–100 ratings).\n\nData: USGS 3DEP elevation, USGS NHD hydrography, FEMA NFHL flood zones, NOAA SLOSH storm surge, FEMA NRI (wind), USFS Wildfire Hazard Potential, USGS National Seismic Hazard Model."},"servers":[{"url":"https://lotrik.co.uk/satinwood","description":"Production"}],"tags":[{"name":"Risk","description":"Flood & environmental risk scoring"},{"name":"Lookup","description":"Address search & parcels"},{"name":"Meta","description":"Health & data coverage"}],"paths":{"/api/risk":{"get":{"tags":["Risk"],"summary":"Risk profile for one location (address OR lat/lng)","description":"Provide either `address` (geocoded via US Census) or `lat`+`lng`. Covers the Continental US.","parameters":[{"name":"address","in":"query","schema":{"type":"string"},"example":"100 N Tryon St Charlotte NC","description":"Free-text US address (used when lat/lng omitted)"},{"name":"lat","in":"query","schema":{"type":"number"},"example":35.8899},{"name":"lng","in":"query","schema":{"type":"number"},"example":-77.5325}],"responses":{"200":{"description":"Risk profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskProfile"}}}},"400":{"description":"Missing/invalid params or outside NC"},"404":{"description":"Address not found"}}}},"/api/risk/{peril}":{"get":{"tags":["Risk"],"summary":"One peril only (flood · wind · wildfire · earthquake)","description":"Returns just the requested peril block — cheaper than the full profile. Accepts `address` or `lat`+`lng`.","parameters":[{"name":"peril","in":"path","required":true,"schema":{"type":"string","enum":["flood","wind","wildfire","earthquake"]}},{"name":"address","in":"query","schema":{"type":"string"},"example":"1 Dr Carlton B Goodlett Pl, San Francisco CA"},{"name":"lat","in":"query","schema":{"type":"number"}},{"name":"lng","in":"query","schema":{"type":"number"}}],"responses":{"200":{"description":"The single-peril block (shape depends on the peril)"},"400":{"description":"Missing params / outside US"},"404":{"description":"Unknown peril or address not found"}}}},"/api/cat":{"get":{"tags":["Risk"],"summary":"Catastrophe EP curve + Average Annual Loss (technical rate)","description":"Actuarial catastrophe output for one location (address OR lat/lng). Returns **AAL** (Average Annual Loss as a % of insured value — a technical rate, no exposure DB needed), a per-peril AAL breakdown, and the **Exceedance-Probability curve** (loss at the 20/50/100/250/500/1000-yr return periods). Built as an empirical event-loss-table from HURDAT2 (hurricane), SPC (tornado), USGS PGA (earthquake), FEMA zones + SLOSH (flood/surge) and USFS WHP (wildfire). Multiply AAL% by the sum insured for an annual expected-loss figure.","parameters":[{"name":"address","in":"query","schema":{"type":"string"},"example":"1 Dr Carlton B Goodlett Pl, San Francisco CA"},{"name":"lat","in":"query","schema":{"type":"number"},"example":25.7617},{"name":"lng","in":"query","schema":{"type":"number"},"example":-80.1918}],"responses":{"200":{"description":"Catastrophe risk (AAL + EP curve)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatRisk"}}}},"400":{"description":"Missing params / outside US"},"404":{"description":"Address not found"}}}},"/api/cat/aal":{"get":{"tags":["Risk"],"summary":"Average Annual Loss only (technical rate + per-peril)","description":"Just the headline **AAL** (% of insured value) and the per-peril AAL breakdown — no EP curve. Address or lat/lng.","parameters":[{"name":"address","in":"query","schema":{"type":"string"}},{"name":"lat","in":"query","schema":{"type":"number"},"example":25.7617},{"name":"lng","in":"query","schema":{"type":"number"},"example":-80.1918}],"responses":{"200":{"description":"AAL + per-peril breakdown"},"400":{"description":"bad params"}}}},"/api/cat/ep":{"get":{"tags":["Risk"],"summary":"Exceedance-Probability curve only","description":"Just the **EP curve** (modelled loss at 20/50/100/250/500/1000-yr return periods) plus AAL. Address or lat/lng.","parameters":[{"name":"address","in":"query","schema":{"type":"string"}},{"name":"lat","in":"query","schema":{"type":"number"},"example":25.7617},{"name":"lng","in":"query","schema":{"type":"number"},"example":-80.1918}],"responses":{"200":{"description":"EP curve"},"400":{"description":"bad params"}}}},"/api/cat/peril/{peril}":{"get":{"tags":["Risk"],"summary":"Single-peril AAL contribution","description":"The AAL (% of value) for one peril only.","parameters":[{"name":"peril","in":"path","required":true,"schema":{"type":"string","enum":["hurricane","tornado","earthquake","flood","wildfire"]}},{"name":"address","in":"query","schema":{"type":"string"}},{"name":"lat","in":"query","schema":{"type":"number"}},{"name":"lng","in":"query","schema":{"type":"number"}}],"responses":{"200":{"description":"peril AAL"},"404":{"description":"unknown peril"}}}},"/api/cat/batch":{"post":{"tags":["Risk"],"summary":"Portfolio catastrophe scoring (AAL per location + portfolio roll-up)","description":"POST an array (max 1000) of addresses and/or lat/lng. Returns the full cat profile per location plus a **portfolio** roll-up (mean AAL across all scored locations) — score an entire book of business in one call.","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"array","items":{"$ref":"#/components/schemas/BatchItem"}},{"type":"object","properties":{"locations":{"type":"array","items":{"$ref":"#/components/schemas/BatchItem"}}}}]},"example":[{"lat":25.7617,"lng":-80.1918},"100 N Tryon St Charlotte NC 28202",[34.05,-118.24]]}}},"responses":{"200":{"description":"Per-location cat_risk + portfolio roll-up","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer"},"portfolio":{"type":"object","properties":{"locations_scored":{"type":"integer"},"mean_aal_pct_of_value":{"type":"number"}}},"results":{"type":"array","items":{"$ref":"#/components/schemas/CatRisk"}}}}}}},"400":{"description":"Not an array / too many items"}}}},"/api/risk/batch":{"post":{"tags":["Risk"],"summary":"Risk profiles for many locations (addresses and/or lat/lng)","description":"POST an array (max 500). Each item may be an address string, `{\"address\":\"...\"}`, `{\"lat\":..,\"lng\":..}`, or `[lat,lng]`. Addresses are geocoded and the resolved coordinates are returned.","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"array","items":{"$ref":"#/components/schemas/BatchItem"}},{"type":"object","properties":{"locations":{"type":"array","items":{"$ref":"#/components/schemas/BatchItem"}}}}]},"example":["416 Glenwood Ave Burlington","100 N Tryon St Charlotte NC 28202",{"lat":35.8899,"lng":-77.5325},[35.9573,-75.6296]]}}},"responses":{"200":{"description":"Ordered results","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer"},"results":{"type":"array","items":{"$ref":"#/components/schemas/BatchResult"}}}}}}},"400":{"description":"Not an array / too many items"}}}},"/api/search":{"get":{"tags":["Lookup"],"summary":"Address autocomplete search","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":3},"example":"Glenwood Ave"}],"responses":{"200":{"description":"Up to 8 matches","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AddressMatch"}}}}}}}},"/api/stats":{"get":{"tags":["Meta"],"summary":"Live data-coverage counts","responses":{"200":{"description":"Row counts per layer"}}}},"/api/health":{"get":{"tags":["Meta"],"summary":"Health check","responses":{"200":{"description":"ok"}}}}},"components":{"schemas":{"BatchItem":{"description":"An address string, {address}, {lat,lng}, or [lat,lng]","oneOf":[{"type":"string","example":"100 N Tryon St Charlotte NC"},{"type":"object","properties":{"address":{"type":"string"}}},{"type":"object","properties":{"lat":{"type":"number"},"lng":{"type":"number"}}},{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2}]},"Resolved":{"type":"object","properties":{"lat":{"type":"number"},"lng":{"type":"number"},"source":{"type":"string","enum":["latlng","address"]},"matched_address":{"type":"string"}}},"Hazard":{"type":"object","properties":{"score":{"type":"integer","description":"≈ % chance over 30 years"},"annual_pct":{"type":"number","description":"annual probability (%)"},"band":{"type":"string","enum":["Very low","Low","Medium","High","Very high"]}}},"Factors":{"type":"object","properties":{"elevation_m":{"type":"number"},"hand_m":{"type":"number","description":"Height Above Nearest Drainage (m)"},"flood_zone":{"type":"string","enum":["FZ3","FZ2","Outside"],"description":"FZ3=SFHA 1% · FZ2=0.2%"},"coastal_zone":{"type":"boolean","description":"in/near a V/VE coastal zone"},"bfe_ft":{"type":"number","description":"Base Flood Elevation (ft, NAVD88)"},"freeboard_m":{"type":"number","description":"elevation − BFE (m); negative = below BFE"},"coast_m":{"type":"number"},"river_m":{"type":"number"},"lake_m":{"type":"number"},"design_wind_mph":{"type":"integer","description":"ASCE-7 basic (3-sec gust) wind speed proxy"},"wbdr":{"type":"boolean","description":"Wind-Borne Debris Region (≤1mi coast & ≥130mph)"},"nciua_beach_plan":{"type":"boolean","description":"in an NCIUA coastal wind-pool county"},"county":{"type":"string"}}},"FloodBlock":{"type":"object","description":"Flood risk (FEMA-zone-anchored) + its sub-hazards","properties":{"score":{"type":"integer"},"band":{"type":"string"},"coastal":{"$ref":"#/components/schemas/Hazard"},"fluvial":{"$ref":"#/components/schemas/Hazard"},"pluvial":{"$ref":"#/components/schemas/Hazard"}}},"WindBlock":{"type":"object","description":"Wind risk (NOAA HURDAT2 hurricane + SPC tornado observed climatology, insurance-grade) + its sub-hazards","properties":{"score":{"type":"integer"},"band":{"type":"string"},"hurricane":{"$ref":"#/components/schemas/Hazard"},"strong_wind":{"$ref":"#/components/schemas/Hazard"},"tornado":{"$ref":"#/components/schemas/Hazard"}}},"RiskProfile":{"type":"object","properties":{"input":{"type":"object"},"resolved":{"$ref":"#/components/schemas/Resolved"},"overall":{"$ref":"#/components/schemas/Hazard","description":"combined flood + wind + wildfire + earthquake"},"flood":{"$ref":"#/components/schemas/FloodBlock"},"wind":{"$ref":"#/components/schemas/WindBlock"},"wildfire":{"$ref":"#/components/schemas/Hazard","description":"USFS Wildfire Hazard Potential (insurance-grade). Adds whp_class 0–5 (dominant fuel class), whp_mean, whp_max."},"earthquake":{"$ref":"#/components/schemas/Hazard","description":"USGS 2%-in-50-yr PGA ground-shaking (insurance-grade)"},"factors":{"$ref":"#/components/schemas/Factors"},"score_meaning":{"type":"string"},"notes":{"type":"array","items":{"type":"string"}}}},"BatchResult":{"type":"object","description":"A RiskProfile with the original input echoed and resolved coords","allOf":[{"$ref":"#/components/schemas/RiskProfile"}],"properties":{"error":{"type":"string"}}},"CatRisk":{"type":"object","description":"Catastrophe EP/AAL output","properties":{"input":{"type":"object"},"resolved":{"$ref":"#/components/schemas/Resolved"},"cat_risk":{"type":"object","properties":{"aal_pct_of_value":{"type":"number","description":"Average Annual Loss as % of insured value (technical rate)"},"aal_per_100k_usd":{"type":"number","description":"AAL in $ per $100,000 of insured value"},"by_peril_aal_pct":{"type":"object","description":"AAL% contribution per peril","properties":{"hurricane":{"type":"number"},"tornado":{"type":"number"},"earthquake":{"type":"number"},"flood":{"type":"number"},"wildfire":{"type":"number"}}},"ep_curve":{"type":"array","description":"Exceedance-probability curve: modelled loss at each return period","items":{"type":"object","properties":{"return_period_yr":{"type":"integer","example":100},"annual_prob":{"type":"number","example":0.01},"loss_pct_of_value":{"type":"number","description":"loss as % of insured value at this return period"}}}},"method":{"type":"string"}}}}},"AddressMatch":{"type":"object","properties":{"parno":{"type":"string"},"siteadd":{"type":"string"},"scity":{"type":"string"},"mzip":{"type":"string"},"parval":{"type":"number"},"lat":{"type":"number"},"lng":{"type":"number"}}}}}}