USGS Seismic Risk API

Give the API a US address or a lat/lon and it returns the ASCE 7-16 design ground-motion values (Ss, S1, PGA, SDS, SD1), the Seismic Design Category (A–F), and a plain-English hazard level for the point. Every response is evaluated live from the USGS Seismic Design Web Services at request time and cites its source. Points outside the USGS model footprint return an explicit unknown — never a silent "no risk."

Base URL

https://seismic-risk-usgs.netlify.app

No API key, no sign-up, no rate-limit tier — call it directly. A metered plan with support is planned; until it exists, this is the only base URL.

GET /seismic-risk

Provide address, OR both lat and lon.

Param	Type	Required	Notes
address	string	one of	US street address. Geocoded via keyless US Census.
lat	number	one of	Latitude −90..90. Requires `lon`.
lon	number	one of	Longitude −180..180. Requires `lat`.
siteClass	string	no	Soil site class `A\|B\|C\|D\|E`. Default `D` (stiff/unknown soil).
riskCategory	string	no	ASCE risk category `I\|II\|III\|IV`. Default `II` (ordinary buildings/homes).
referenceDocument	string	no	`asce7-16` (default), `asce7-22`, or `asce7-10`.

Example

GET /seismic-risk?lat=34.05&lon=-118.25

{
  "query": { "lat": 34.05, "lon": -118.25 },
  "assumptions": { "siteClass": "D", "riskCategory": "II", "referenceDocument": "asce7-16" },
  "location": { "matchedAddress": null, "lat": 34.05, "lon": -118.25, "county": "Los Angeles County" },
  "result": {
    "coverage": "mapped",
    "hazardLevel": "very-high",
    "seismicDesignCategory": "D",
    "sdcAsReportedByUsgs": null,
    "groundMotion": {
      "unit": "g",
      "ss": 1.97, "s1": 0.701, "pga": 0.844,
      "sds": 1.313, "sd1": null, "sms": 1.97, "sm1": null
    },
    "modelVersion": "v4.0.x",
    "meaning": "Very high seismic hazard — at or near a major active fault...",
    "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..."
  },
  "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-21T00:00:00.000Z",
  "disclaimer": "Seismic values are evaluated live from the USGS National Seismic Hazard Model..."
}

The `coverage` field (read this)

Value	Meaning
`mapped`	USGS returned design values for the point. `groundMotion` and `hazardLevel` are populated.
`out_of_model`	Point is outside the USGS model footprint (e.g. open ocean). `groundMotion` and `seismicDesignCategory` are `null`. Guidance provided. HTTP is still 200.

Honesty by design: when USGS has no value for a point, hazardLevel is "unknown" and the numbers are null — the API never converts "no data" into "no earthquake risk." Separately, in high-seismic areas on Site Class D, ASCE 7-16 §11.4.8 requires a site-specific study, so USGS withholds the single overall SDC (sdcAsReportedByUsgs: null). The API then reports the minimum category from the short-period value and includes a designNote saying an engineer must confirm.

Ground-motion fields

Field	Meaning
`ss`	MCE_R spectral response acceleration at 0.2s (short period), g. Site-class independent. The headline hazard number.
`s1`	MCE_R spectral response acceleration at 1.0s, g. Site-class independent.
`pga`	MCE_G peak ground acceleration, g. Site-class independent.
`sds` / `sd1`	Design spectral response accelerations (2/3 of site-modified MCE_R), site-adjusted.
`sms` / `sm1`	Site-modified MCE_R (Ss/S1 × site coefficient Fa/Fv).

Hazard levels & Seismic Design Category

hazardLevel	SDC	Meaning
very-low	A	Damaging earthquakes rare; no special detailing.
low	B	Infrequent, usually minor; light detailing.
moderate	C	Occasional moderate events; moderate design.
high	D	Strong shaking expected; substantial design.
very-high	E / F	Near a major fault; strongest provisions + site-specific study.

GET /health

Discovery + uptime document. Returns { "status": "ok", ... } and the endpoint catalog.

Errors

Status	When
400	Missing/invalid params (no address and not both lat+lon).
404	Address could not be geocoded.
422	lat/lon out of valid range.
405	Non-GET method.
502	USGS service unreachable/errored. Retry shortly.

Notes

Keyless and stateless — safe to cache, and safe behind a proxy or gateway.
CORS is open (*) so you can call it directly from a browser app.
Data is live USGS NSHM via the Seismic Design Web Services; treat results as informational, not a site-specific engineering study. The SDC depends on the actual soil (Site Class).

Machine-readable spec

The full API is described in OpenAPI 3.1 — import it into Postman, Insomnia, or a client generator, or hand it to an agent. The response schemas in it were generated from real responses this API actually returned, not written by hand, so they describe what you will receive rather than what someone intended you to receive.

https://seismic-risk-usgs.netlify.app/openapi.json