{"openapi":"3.1.0","info":{"title":"HailScore Pro API","version":"1.0.0","description":"Address-level hail risk scoring backed by live NOAA MRMS radar, finalized SWDI archives, and NWS active warnings. The same engine that powers myhailscore.com is available behind API-key authentication for roofing CRMs, insurance adjusters, and storm-restoration software.","contact":{"name":"HailScore","email":"hello@myhailscore.com","url":"https://www.myhailscore.com"},"license":{"name":"Commercial — see Terms of Service","url":"https://www.myhailscore.com/terms"},"termsOfService":"https://www.myhailscore.com/terms"},"servers":[{"url":"https://www.myhailscore.com","description":"Production"}],"externalDocs":{"description":"Human-readable API docs + methodology white paper","url":"https://www.myhailscore.com/docs/api"},"security":[{"bearerAuth":[]},{"apiKeyQuery":[]}],"paths":{"/api/v1/lookup":{"get":{"summary":"Address-level HailScore lookup","description":"Returns the HailScore plus a storm summary for a single US address. Equivalent to a homeowner lookup at myhailscore.com but in a stable JSON shape for third-party integration.","operationId":"lookupAddress","tags":["Scoring"],"parameters":[{"in":"query","name":"address","required":true,"schema":{"type":"string","minLength":5},"description":"Full US street address (geocoded via Mapbox).","example":"1701 Franklin Ave, Waco, TX 76701"}],"responses":{"200":{"description":"Score returned successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LookupResponse"},"example":{"request":{"address":"1701 Franklin Ave, Waco, TX 76701","resolved_address":"1701 Franklin Avenue, Waco, Texas 76701, United States","lat":31.5493,"lon":-97.1467},"score":{"value":67,"tier":"High","max_hail_size_in":4},"storms":{"total_radar_events":851,"last_damaging_event":{"date":"2024-05-31","size":2.75,"days_ago":349},"claim_window_open":true},"live_mrms":{"hail_days_last_30":1,"max_in_last_30":0.85},"meta":{"api_version":"v1","generated_at":"2026-05-15T03:00:00Z","sources":["NOAA Storm Events","NCEP MRMS","NEXRAD MESH (SWDI)","SPC LSR","NWS Active Alerts"]}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"description":"Geocoding failed (address could not be resolved)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"geocode_failed","address":"garbled input"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"API key formatted as `hs_live_<8hex>_<24 base64url>`. Generate keys in the contractor dashboard at /dashboard/api-keys."},"apiKeyQuery":{"type":"apiKey","in":"query","name":"api_key","description":"Same API key as above, passed via query parameter. Bearer header is preferred for production."}},"schemas":{"LookupResponse":{"type":"object","required":["request","score","storms","live_mrms","meta"],"properties":{"request":{"$ref":"#/components/schemas/LookupRequest"},"score":{"$ref":"#/components/schemas/Score"},"storms":{"$ref":"#/components/schemas/StormSummary"},"live_mrms":{"$ref":"#/components/schemas/LiveMrms"},"meta":{"$ref":"#/components/schemas/ResponseMeta"}}},"LookupRequest":{"type":"object","required":["address","resolved_address","lat","lon"],"properties":{"address":{"type":"string","description":"Address as submitted."},"resolved_address":{"type":"string","description":"Address after Mapbox geocoding canonicalization."},"lat":{"type":"number","format":"float","minimum":-90,"maximum":90},"lon":{"type":"number","format":"float","minimum":-180,"maximum":180}}},"Score":{"type":"object","required":["value","tier","max_hail_size_in"],"properties":{"value":{"type":"integer","minimum":0,"maximum":100,"description":"0-100 HailScore."},"tier":{"type":"string","enum":["Low","Moderate","High","Very High"],"description":"Tier mapping: 0-25 Low, 26-50 Moderate, 51-75 High, 76-100 Very High."},"max_hail_size_in":{"type":"number","format":"float","description":"Largest hailstone (inches) recorded near the address in the scoring window."}}},"StormSummary":{"type":"object","required":["total_radar_events","last_damaging_event","claim_window_open"],"properties":{"total_radar_events":{"type":"integer","description":"Count of radar-derived hail events within 8 miles in the scoring window."},"last_damaging_event":{"oneOf":[{"$ref":"#/components/schemas/DamagingEvent"},{"type":"null"}],"description":"Most recent event ≥1.0″ — drives the claim-window calculation."},"claim_window_open":{"type":"boolean","description":"True when the last damaging event is within the typical 2-year claim filing window. Carriers may vary; not legal advice."}}},"DamagingEvent":{"type":"object","required":["date","size","days_ago"],"properties":{"date":{"type":"string","format":"date","example":"2024-05-31"},"size":{"type":"number","format":"float","description":"Hail size in inches."},"days_ago":{"type":"integer","minimum":0}}},"LiveMrms":{"type":"object","required":["hail_days_last_30"],"properties":{"hail_days_last_30":{"type":"integer","description":"Distinct days in the last 30 with ≥1.0″ MRMS hail within 5 mi."},"max_in_last_30":{"oneOf":[{"type":"number","format":"float"},{"type":"null"}],"description":"Maximum MRMS hail size (inches) observed in the last 30 days, or null if none."}}},"ResponseMeta":{"type":"object","required":["api_version","generated_at","sources"],"properties":{"api_version":{"type":"string","example":"v1"},"generated_at":{"type":"string","format":"date-time"},"sources":{"type":"array","items":{"type":"string"},"description":"Data feeds cited in producing this response."}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying — only present on 429 responses."}}}},"responses":{"BadRequest":{"description":"Missing or invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"address query param required"}}}},"Unauthorized":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Invalid or revoked API key."}}}},"RateLimited":{"description":"Per-key rate limit exceeded — see retry_after","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded (minute-rate-limit)","retry_after":38}}}}}},"tags":[{"name":"Scoring","description":"Address-level HailScore + storm summary endpoints."}]}