{"openapi":"3.0.3","info":{"title":"Satinwood — North Carolina Flood & Environmental Risk API","version":"2.0.0","description":"Property-level **flood & wind** risk for North Carolina. Every profile returns an **overall** score plus two 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** → hurricane / strong-wind / tornado sub-scores from the **FEMA National Risk Index**, an ASCE-7 design-wind proxy, plus **WBDR** and **NCIUA Beach-Plan** overlays.\n\nOverall = `1 − (1 − flood)(1 − wind)`. Scores are 0–100 ratings.\n\nData: USGS 3DEP 10 m elevation, USGS NHD hydrography, FEMA NFHL flood zones, FEMA NRI, NC OneMap parcels."},"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` (fuzzy-geocoded against NC parcels) or `lat`+`lng`.","parameters":[{"name":"address","in":"query","schema":{"type":"string"},"example":"100 N Tryon St Charlotte NC","description":"Free-text NC 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/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/parcel":{"get":{"tags":["Lookup"],"summary":"Nearest parcel to a coordinate","parameters":[{"name":"lat","in":"query","required":true,"schema":{"type":"number"},"example":35.7796},{"name":"lng","in":"query","required":true,"schema":{"type":"number"},"example":-78.6382}],"responses":{"200":{"description":"Nearest parcel (address, owner, tax value, distance)"}}}},"/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 (FEMA NRI + design wind) + 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"},"flood":{"$ref":"#/components/schemas/FloodBlock"},"wind":{"$ref":"#/components/schemas/WindBlock"},"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"}}},"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"}}}}}}