{ "openapi": "3.1.0", "info": { "title": "USGS Seismic Risk / Earthquake Hazard API", "version": "1.0.0", "summary": "Earthquake hazard, ASCE 7 Seismic Design Category and design ground motions for any US address.", "description": "Earthquake hazard, ASCE 7 Seismic Design Category and design ground motions for any US address.\n\nNo API key is required. Data comes from official US government sources and is attributed in each response. Where the underlying model does not cover a location, the API says so explicitly rather than returning a confident wrong answer.", "contact": { "email": "chris.ellington13@gmail.com" }, "license": { "name": "Proprietary", "identifier": "LicenseRef-Proprietary" } }, "servers": [ { "url": "https://seismic-risk-usgs.netlify.app", "description": "Production" } ], "tags": [ { "name": "Seismic", "description": "Earthquake hazard lookups" }, { "name": "Meta", "description": "Service metadata" } ], "paths": { "/seismic-risk": { "get": { "tags": [ "Seismic" ], "operationId": "getSeismicRisk", "summary": "Seismic hazard and design values for a location", "description": "Give a US address or a lat/lon and get the USGS ASCE 7 design ground-motion values (Ss, S1, PGA, SDS, SD1), the Seismic Design Category (A–F) and a plain-English hazard level. Provide `address` OR both `lat` and `lon`. Points outside the USGS model footprint return `coverage: \"out_of_model\"` with an explicit unknown — never a silent \"no risk\".", "x-probes": { "default": "/seismic-risk?address=1%20Dr%20Carlton%20B%20Goodlett%20Pl,%20San%20Francisco%20CA" }, "parameters": [ { "name": "address", "in": "query", "required": false, "description": "US street address. Optional if lat/lon are given.", "schema": { "type": "string" }, "example": "1 Dr Carlton B Goodlett Pl, San Francisco CA" }, { "name": "lat", "in": "query", "required": false, "description": "Latitude, -90..90. Requires lon.", "schema": { "type": "number" } }, { "name": "lon", "in": "query", "required": false, "description": "Longitude, -180..180. Requires lat.", "schema": { "type": "number" } }, { "name": "siteClass", "in": "query", "required": false, "description": "ASCE soil site class. Default D (stiff/unknown soil).", "schema": { "type": "string", "enum": [ "A", "B", "C", "D", "E" ] } }, { "name": "riskCategory", "in": "query", "required": false, "description": "ASCE risk category. Default II (ordinary buildings and homes).", "schema": { "type": "string", "enum": [ "I", "II", "III", "IV" ] } }, { "name": "referenceDocument", "in": "query", "required": false, "description": "ASCE edition. Default asce7-16.", "schema": { "type": "string", "enum": [ "asce7-16", "asce7-22", "asce7-10" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "object", "properties": { "address": { "type": "string" } } }, "assumptions": { "type": "object", "properties": { "siteClass": { "type": "string" }, "riskCategory": { "type": "string" }, "referenceDocument": { "type": "string" }, "note": { "type": "string" } } }, "location": { "type": "object", "properties": { "matchedAddress": { "type": "string" }, "lat": { "type": "number" }, "lon": { "type": "number" }, "county": { "type": "string" }, "countyFips": { "type": "string" }, "zip": { "type": "string" } } }, "result": { "type": "object", "properties": { "coverage": { "type": "string" }, "hazardLevel": { "type": "string" }, "seismicDesignCategory": { "type": "string" }, "sdcAsReportedByUsgs": { "type": [ "null" ] }, "groundMotion": { "type": "object", "properties": { "unit": { "type": "string" }, "ss": { "type": "number" }, "s1": { "type": "number" }, "pga": { "type": "number" }, "sds": { "type": "integer" }, "sd1": { "type": "integer" }, "sms": { "type": "number" }, "sm1": { "type": "integer" } } }, "modelVersion": { "type": "string" }, "meaning": { "type": "string" }, "designNote": { "type": "string" } } }, "source": { "type": "object", "properties": { "seismicData": { "type": "string" }, "seismicService": { "type": "string" }, "geocoder": { "type": "string" } } }, "retrievedAt": { "type": "string" }, "disclaimer": { "type": "string" } } }, "example": { "query": { "address": "1 Dr Carlton B Goodlett Pl, San Francisco CA" }, "assumptions": { "siteClass": "D", "riskCategory": "II", "referenceDocument": "asce7-16", "note": "Seismic Design Category depends on Site Class (soil). Default D = \"stiff soil / unknown soil\". Override with ?siteClass=A|B|C|D|E and ?riskCategory=I|II|III|IV." }, "location": { "matchedAddress": "1 DR CARLTON P GOODLETT PL, SAN FRANCISCO, CA, 94102", "lat": 37.778532096981, "lon": -122.418308756397, "county": "San Francisco County", "countyFips": "06075", "zip": "94102" }, "result": { "coverage": "mapped", "hazardLevel": "very-high", "seismicDesignCategory": "D", "sdcAsReportedByUsgs": null, "groundMotion": { "unit": "g", "ss": 1.5, "s1": 0.6, "pga": 0.565, "sds": 1, "sd1": 0, "sms": 1.5, "sm1": 0 }, "modelVersion": "v4.0.x", "meaning": "Very high seismic hazard — at or near a major active fault. Very strong ground shaking is likely and the most stringent seismic-design provisions apply. A site-specific ground-motion study is typically required. The ASCE 7 Seismic Design Category here is D. (Short-period design value Ss ≈ 1.5 g — the standard headline measure of ground-shaking hazard.)", "designNote": "USGS did not return a single overall Seismic Design Category for Site Class D: ASCE 7-16 §11.4.8 requires a site-specific ground-motion analysis where S1 ≥ 0.2 g (a high-seismic condition). The category shown (D) is the minimum from the short-period value; a licensed engineer must confirm the governing category." }, "source": { "seismicData": "USGS Seismic Design Web Services (ASCE 7-16), evaluating the USGS National Seismic Hazard Model", "seismicService": "https://earthquake.usgs.gov/ws/building-codes/asce7-16/calculate", "geocoder": "US Census Geocoder (geographies/onelineaddress, Public_AR_Current)" }, "retrievedAt": "2026-07-25T21:42:23.389Z", "disclaimer": "Seismic values are evaluated live from the USGS National Seismic Hazard Model via the USGS Seismic Design Web Services. This is informational only — it is NOT a substitute for a site-specific geotechnical or structural engineering study, a soil (Site Class) determination, or the governing local building code. The Seismic Design Category depends on the actual Site Class; verify with a licensed engineer before any design, financial, or insurance decision." } } } }, "400": { "description": "The request did not identify a location (no address, ZIP or lat/lon).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/health": { "get": { "tags": [ "Meta" ], "operationId": "getHealth", "summary": "Service metadata and status", "description": "The service description, version and endpoint documentation. Also serves as a liveness check.", "x-probes": { "default": "/health" }, "parameters": [], "responses": { "200": { "description": "Service is up", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "status": { "type": "string" }, "version": { "type": "string" }, "description": { "type": "string" }, "endpoints": { "type": "object", "properties": { "/seismic-risk": { "type": "object", "properties": { "method": { "type": "string" }, "params": { "type": "object", "properties": { "address": { "type": "string" }, "lat": { "type": "string" }, "lon": { "type": "string" }, "siteClass": { "type": "string" }, "riskCategory": { "type": "string" }, "referenceDocument": { "type": "string" } } }, "note": { "type": "string" }, "examples": { "type": "array", "items": { "type": "string" } } } }, "/health": { "type": "object", "properties": { "method": { "type": "string" }, "note": { "type": "string" } } } } }, "coverageHonesty": { "type": "string" }, "dataSource": { "type": "object", "properties": { "seismicData": { "type": "string" }, "seismicService": { "type": "string" }, "geocoder": { "type": "string" } } }, "docs": { "type": "string" } } }, "example": { "name": "USGS Seismic Risk / Earthquake Hazard API", "status": "ok", "version": "1.0.0", "description": "Keyless US earthquake-hazard lookup. Give a US address or lat/lon and get the USGS ASCE 7-16 design ground-motion values (Ss, S1, PGA, SDS, SD1), the Seismic Design Category (A–F), and a plain-English hazard level (very-low..very-high) — with HONEST handling of points outside the USGS model footprint.", "endpoints": { "/seismic-risk": { "method": "GET", "params": { "address": "US street address (optional if lat/lon given)", "lat": "latitude -90..90 (optional if address given; requires lon)", "lon": "longitude -180..180 (optional if address given; requires lat)", "siteClass": "ASCE soil site class A|B|C|D|E (optional, default D = stiff/unknown soil)", "riskCategory": "ASCE risk category I|II|III|IV (optional, default II = ordinary buildings/homes)", "referenceDocument": "asce7-16|asce7-22|asce7-10 (optional, default asce7-16)" }, "note": "Provide address OR (lat AND lon).", "examples": [ "/seismic-risk?address=1 Dr Carlton B Goodlett Pl, San Francisco CA", "/seismic-risk?lat=34.05&lon=-118.25", "/seismic-risk?lat=30&lon=-45 (example of an OUT-OF-MODEL location)" ] }, "/health": { "method": "GET", "note": "This document; returns status ok." } }, "coverageHonesty": "The USGS model covers the US and its territories, not the whole globe. When a point is outside the model footprint the API returns coverage:\"out_of_model\" with an explicit unknown and guidance — it will never return a silent \"no earthquake risk.\" In high-seismic areas on Site Class D, ASCE 7-16 §11.4.8 requires a site-specific study and USGS withholds the overall Seismic Design Category; the API reports the minimum category and flags that an engineer must confirm.", "dataSource": { "seismicData": "USGS Seismic Design Web Services (evaluates the USGS National Seismic Hazard Model)", "seismicService": "https://earthquake.usgs.gov/ws/building-codes/asce7-16/calculate", "geocoder": "US Census Geocoder (keyless)" }, "docs": "/api-docs.html" } } } } } } } } }