# USGS Seismic Design Screener - ASCE 7-22 & 7-16 SDC Lookup (`malonestar/usgs-seismic-design-screener`) Actor

Batch coordinates to ASCE 7 seismic design values from the keyless USGS service. Each row carries the edition you pick AND ASCE 7-22, the current standard: SDS, SD1, SDC, SS, S1, SMS, SM1, PGA\_M, Fa, Fv, TL, design spectra, ASCE 41-17 retrofit levels. MCP-ready. Screening aid, not a stamped design.

- **URL**: https://apify.com/malonestar/usgs-seismic-design-screener.md
- **Developed by:** [Kyle Maloney](https://apify.com/malonestar) (community)
- **Categories:** Developer tools, Agents, Real estate
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.30 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## USGS Seismic Design Screener - ASCE 7-22 & 7-16 SDC by coordinate

Batch a list of coordinates into **ASCE 7 seismic design parameters** from the keyless
USGS building-codes web service. One row per site, with **both the edition you select and
ASCE 7-22 - the current standard - on the same row**.

Per site you get SDS, SD1, the Seismic Design Category (A-F), SS, S1, SMS, SM1, PGA and
PGA\_M, Fa, Fv, F\_PGA, TL, Ts, T0, the uniform-hazard and risk-targeted underlying values,
the full design and MCE\_R **response spectra**, the USGS hazard-model version, a
plain-language reading of what the SDC means - and, where the standard you picked cannot
finalize a design value, the ASCE 7-22 answer that usually can.

This is a **screening and portfolio-triage tool**. It is not a substitute for a
site-specific seismic hazard study, and nothing here is a stamped engineering
determination.

***

### Why the ASCE edition matters more than you would think

ASCE 7-16 refuses to finalize SD1 and the Seismic Design Category for high-seismicity
sites on soft soil (Sec. 11.4.8, Site Class D/E with S1 >= 0.2). It returns SD1 null,
SDC null, Fv null and the note "See Section 11.4.8". ASCE 7-22 replaced that two-
coefficient site-amplification method with multi-period response spectra and **resolves
most of those sites outright.**

Live, from this actor:

| Site | ASCE 7-16 | ASCE 7-22 |
|---|---|---|
| San Francisco, CA - Site Class D | SDS 1.0, **SD1 null, SDC null** (site-specific study) | SDS 1.16, **SD1 1.17, SDC D** |
| Memphis, TN hospital - Risk IV, Site Class E | **SDS null, SD1 null, SDC null** | SDS 0.53, **SD1 0.40, SDC D** |
| Chicago, IL - Site Class D | SDS 0.124, SD1 0.100, SDC B | SDS 0.13, SD1 0.099, SDC B |

If your authority having jurisdiction has adopted **IBC 2024**, ASCE 7-22 is the standard
that governs, and a 7-16 "site-specific study required" result is an artifact of a
superseded edition - not a property of your site. The `current_edition_note` column says
so in plain language on every row, and `asce722_sdc_vs_primary` tells you whether the two
editions agree.

`referenceDocument` still defaults to **asce7-16** so existing integrations keep the exact
values they were built on. The ASCE 7-22 cross-check is added alongside, in its own
`asce722_*` columns. **No existing column ever changed meaning.**

***

### Who this is for

- **Structural engineers** pulling SDS / SD1 / SDC for a batch of candidate sites, or
  checking a design against the edition their jurisdiction actually adopted.
- **Geotechnical engineers** who need **PGA\_M** (`pgam`) for the ASCE 7 Sec. 11.8.3
  liquefaction screen - not the mapped `pga`, which is the pre-site-coefficient value.
- **Building-code and permitting consultants** reconciling a project designed under
  ASCE 7-16 with a jurisdiction that has moved to ASCE 7-22.
- **Solar, BESS and data-centre site selection** teams ranking dozens or hundreds of
  parcels by seismic band before anyone visits.
- **Existing-building / retrofit teams** who need ASCE 41-17 BSE-2N / BSE-1N / BSE-2E /
  BSE-1E hazard levels for a Tier 1-3 evaluation.
- **Insurance and catastrophe-risk modellers** attaching a code-basis seismic parameter
  to a portfolio of locations.
- **AI agents** - see the MCP note below.

***

### Example input

```json
{
  "assets": [
    { "lat": 37.7749, "lon": -122.4194, "label": "San Francisco, CA" },
    { "lat": 41.8781, "lon": -87.6298, "label": "Chicago, IL" },
    {
      "lat": 35.1495, "lon": -90.0490,
      "label": "Memphis TN hospital (New Madrid, soft soil)",
      "riskCategory": "IV",
      "siteClass": "E"
    }
  ],
  "riskCategory": "II",
  "siteClass": "D",
  "referenceDocument": "asce7-16",
  "includeCurrentEdition": true,
  "includeSpectra": true,
  "verifyUpstream": true
}
```

`riskCategory` and `siteClass` set the run-wide default; any site can override either.
Site Class **D** is the code default when the soil is unknown - if you have a geotechnical
report, supply the measured class per site, because it changes every design value.

#### Inputs

| Input | Default | What it does |
|---|---|---|
| `assets` | *required* | Sites to screen: `lat`, `lon`, `label`, optional `riskCategory` and `siteClass`. |
| `riskCategory` | `II` | ASCE 7 Risk Category default. I = low hazard, II = ordinary, III = substantial hazard, IV = essential (hospitals, fire stations). |
| `siteClass` | `D` | ASCE 7 Site Class default. A = hard rock, B = rock, C = very dense soil / soft rock, D = stiff soil, E = soft clay. |
| `referenceDocument` | `asce7-16` | `asce7-16`, `asce7-22` (current), `asce7-10`, `asce7-05`, `asce41-17`, `nehrp-2015`, `nehrp-2020`. |
| `includeCurrentEdition` | `true` | Adds the ASCE 7-22 cross-check columns. Does not change billing. |
| `includeSpectra` | `true` | Emits the design and MCE\_R response-spectrum arrays. |
| `verifyUpstream` | `true` | Probes three canary points and fails the run if USGS has drifted (see below). |
| `maxAssets` | `500` | Safety cap. Sites beyond it are not screened and the log says so. |

#### Reference documents, verified live

| Slug | Standard | USGS hazard model | Notes |
|---|---|---|---|
| `asce7-22` | ASCE 7-22 (**current**, IBC 2024) | v5.0.x | Multi-period spectra. Defines **no** Fa, Fv, PGA or F\_PGA - use `pgam` for PGA\_M. |
| `asce7-16` | ASCE 7-16 (IBC 2018/2021) | v4.0.x | Default. Sec. 11.4.8 nulls SD1/SDC on high-seismic soft soil. |
| `asce7-10` | ASCE 7-10 (IBC 2012/2015) | v3.1.x | Full parameter set. |
| `asce7-05` | ASCE 7-05 (IBC 2006/2009) | v2.0.x | Defines no PGA family at all. |
| `asce41-17` | ASCE 41-17 evaluation & retrofit | v4.0.x | Returns BSE-2N/1N/2E/1E hazard levels (SXS, SX1), **not** SDS/SD1/SDC. |
| `nehrp-2015` | NEHRP 2015 provisions | v4.0.x | Same shape as ASCE 7-16. |
| `nehrp-2020` | NEHRP 2020 provisions | v5.0.x | Same shape as ASCE 7-22. |

`asce41-23` exists on the service but self-identifies as **Beta** and omits `request.status`,
so it is deliberately not offered.

***

### Output fields

Every run emits all 86 columns on every row. A field is `null` when it was **not checked**; `false` and `0` are answers. `parameters_not_defined_in_edition` lists the columns the standard you picked does not define at all.

#### Site identity

| Field | Type | Description |
|---|---|---|
| `asset_label` | string | Your name for the screened site, echoed back from the input. |
| `asset_lat` | number | null | Latitude of the site (WGS84). |
| `asset_lon` | number | null | Longitude of the site (WGS84). |
| `risk_category` | string | null | ASCE 7 Risk Category used for this site (I, II, III, or IV). |
| `site_class` | string | null | ASCE 7 Site Class (soil profile) used for this site (A-E). |
| `reference_document` | string | null | The ASCE / NEHRP reference document the values in this row were computed under: asce7-16 (default), asce7-22 (current edition, IBC 2024), asce7-10, asce7-05, asce41-17, nehrp-2015 or nehrp-2020. |
| `edition_family` | string | null | Which payload family the selected reference document belongs to: asce7 (ASCE 7 design values), nehrp (NEHRP provisions, same shape as the corresponding ASCE 7 edition), or asce41 (ASCE 41 seismic evaluation and retrofit hazard levels). |
| `is_current_asce7_edition` | boolean | null | True when reference\_document is asce7-22, the current edition of ASCE 7 (referenced by IBC 2024). False for superseded editions and for ASCE 41. |
| `service_reference_document` | string | null | The reference document the USGS service reported back for this request. Compared against the edition that was requested on every row: a mismatch means USGS silently re-pointed the path segment and the row is failed rather than resolved. |

#### Outcome and provenance

| Field | Type | Description |
|---|---|---|
| `primary_status` | string | null | Outcome of the lookup under the SELECTED reference document. ok = design values resolved. site\_specific = base accelerations resolved but the service returned no final SD1/SDC. no\_coverage = the point is outside the hazard model. unavailable = the service failed or answered for the wrong edition. invalid\_input = the supplied lat/lon was rejected before any request was made. Null design values mean different things under each of these, so read this before reading a null. |
| `primary_error` | string | null | The reason the lookup under the selected reference document did not resolve. Null on a healthy row - null here is good news, not a dead column. |
| `error` | string | null | Populated on ERROR rows only (invalid lat/lon, out-of-coverage point, service failure, or a payload that failed the shape/edition check); null otherwise. One bad point never fails the run - but if EVERY point fails upstream the run is failed so nothing is billed. |
| `parameters_not_defined_in_edition` | string | null | Comma-separated list of output columns the SELECTED standard does not define at all, so that a null there is read as not-applicable rather than not-checked. ASCE 7-22 replaced the Fa/Fv site-coefficient method with multi-period response spectra and returns "pga,fpga,fa,fv,sdcs,sdc1"; ASCE 7-05 predates the PGA parameters and returns "pga,pgam,fpga,cv,ts,t0"; ASCE 7-16 returns an empty string. Never null on a resolved ASCE 7 row. |
| `model_version` | string | null | The USGS national seismic hazard model version behind these values. Differs by edition: v2.0.x for ASCE 7-05, v3.1.x for 7-10, v4.0.x for 7-16 and ASCE 41-17, v5.0.x for 7-22 and NEHRP-2020. Record this with any design value you keep. |
| `spatial_interpolation_method` | string | null | How the service interpolated the gridded hazard data to your exact coordinate. |
| `service_version` | string | null | Build version of the USGS erp-design-ws service that answered the request. |
| `source_url` | string | The exact USGS ASCE 7 web-service request URL used for this site. |
| `checked_at` | string | UTC timestamp (ISO 8601) when the lookup ran. |
| `disclaimer` | string | null | Advisory-use notice: informational screening aid, not a stamped engineering determination. |

#### Design values (selected edition)

| Field | Type | Description |
|---|---|---|
| `ss` | number | null | Mapped MCE\_R spectral response acceleration at short periods (0.2 s), as a fraction of gravity g. |
| `s1` | number | null | Mapped MCE\_R spectral response acceleration at a 1-second period, as a fraction of g. |
| `sms` | number | null | Site-modified MCE\_R spectral response acceleration at short periods, as a fraction of g (ASCE 7 Eq. 11.4-1: SMS = Fa x SS). SDS is two thirds of this. |
| `sm1` | number | null | Site-modified MCE\_R spectral response acceleration at a 1-second period, as a fraction of g (ASCE 7 Eq. 11.4-2: SM1 = Fv x S1). SD1 is two thirds of this. |
| `sds` | number | null | Design spectral response acceleration at short periods, as a fraction of g. A primary ASCE 7 design value. |
| `sd1` | number | null | Design spectral response acceleration at a 1-second period, as a fraction of g. Null when the selected edition requires a site-specific study - check asce722\_sd1, because ASCE 7-22 usually resolves those sites. |
| `sdc` | string | null | Seismic Design Category letter (A-F) governing detailing and system requirements under the SELECTED reference document. Null when a site-specific study is required; sdc\_minimum then carries the hard lower bound and asce722\_sdc carries the current-edition answer. |
| `sdcs` | string | null | Seismic Design Category derived from SDS alone (ASCE 7 Table 11.6-1). The governing SDC is the more severe of this and SDC1. Not defined by ASCE 7-22. |
| `sdc1` | string | null | Seismic Design Category derived from SD1 alone (ASCE 7 Table 11.6-2). The governing SDC is the more severe of this and SDCS. Not defined by ASCE 7-22. |
| `sdc_minimum` | string | null | Best available Seismic Design Category for the site: the final `sdc` when the service gave one, otherwise the more severe of the SDCS/SDC1 pair that did resolve. When a site-specific study is triggered the service nulls `sdc` but often still reports SDCS, which is a hard lower bound - San Francisco Site Class D returns sdc null and sdcs "D", so the answer is "at least D", not "unknown". Null only when neither sub-category resolved. |
| `sdc_is_final` | boolean | null | True when the service returned a finalized Seismic Design Category. False when sdc\_minimum is only a lower bound because a site-specific study is required. Null when the lookup did not resolve at all. |
| `sdc_meaning` | string | null | Plain-language summary of what the governing Seismic Design Category implies for detailing, permitted structural systems and geotechnical work. Derived from sdc\_minimum, so it is present even when a site-specific study prevented a final SDC. |
| `seismicity_band` | string | null | Coarse triage band derived from SDS using the ASCE 7 Table 11.6-1 breakpoints: very low (<0.167), low (<0.33), moderate (<0.50), high (<1.0), very high (>=1.0). For an ASCE 41 lookup it is derived from the BSE-1N SXS, which is the ASCE 41 analogue of SDS. Null when no design acceleration resolved. |

#### Ground acceleration and site coefficients

| Field | Type | Description |
|---|---|---|
| `pga` | number | null | MAPPED MCE\_G peak ground acceleration, as a fraction of gravity g, before the site coefficient is applied. For geotechnical and liquefaction evaluation ASCE 7 Sec. 11.8.3 requires the SITE-ADJUSTED value PGA\_M - use the `pgam` column for that (PGA\_M = F\_PGA x PGA). Not defined by ASCE 7-05 or ASCE 7-22; see parameters\_not\_defined\_in\_edition. |
| `pgam` | number | null | Site-adjusted MCE\_G peak ground acceleration PGA\_M, as a fraction of g (PGA\_M = F\_PGA x PGA). This - not the mapped `pga` column - is the value ASCE 7 Sec. 11.8.3 requires for liquefaction and geotechnical evaluation. Present under ASCE 7-10/7-16/7-22; ASCE 7-05 does not define it. |
| `fpga` | number | null | Site coefficient applied to the mapped PGA for the soil site class. Not defined by ASCE 7-05 or ASCE 7-22. |
| `fa` | number | null | Short-period site coefficient applied to SS for the soil site class. Not defined by ASCE 7-22, which replaced the Fa/Fv method with multi-period response spectra. |
| `fv` | number | null | 1-second-period site coefficient applied to S1. Null with fv\_note "See Section 11.4.8" when an ASCE 7-16 site-specific study is triggered. Not defined by ASCE 7-22. |
| `fa_note` | string | null | The note the USGS service attached to Fa, if any. Populated when a code section overrides the tabulated value. |
| `fv_note` | string | null | The note the USGS service attached to Fv, if any. This is the field that carries the ASCE 7-16 Sec. 11.4.8 site-specific trigger. |
| `tl` | number | null | Long-period transition period, in seconds. |
| `ts` | number | null | Transition period between the constant-acceleration and constant-velocity branches of the design response spectrum, in seconds (Ts = SD1 / SDS). |
| `t0` | number | null | Period at which the ascending branch of the design response spectrum meets SDS, in seconds (T0 = 0.2 x Ts). |
| `cv` | number | null | Vertical ground-motion coefficient used to build the vertical response spectrum (ASCE 7-16 Sec. 11.9). Not defined by ASCE 7-05. |

#### Site-specific study

| Field | Type | Description |
|---|---|---|
| `site_specific_study_required` | boolean | null | True when the service resolved base accelerations but could not finalize SD1/SDC for this high-seismicity + soft-soil combination, meaning a site-specific ground-motion procedure is required (ASCE 7-16 Sec. 11.4.8). This is edition-dependent: ASCE 7-22 resolves most of these sites outright, so check asce722\_sd1 / asce722\_sdc before commissioning a study. False when no study was triggered. |
| `site_specific_reason` | string | null | Why the service could not finalize SD1/SDC for this site, quoting the note the USGS service itself returned (typically "See Section 11.4.8"). Null when no site-specific study was triggered. |

#### Underlying hazard values

| Field | Type | Description |
|---|---|---|
| `ssuh` | number | null | Uniform-hazard (2% in 50 years) short-period spectral acceleration before the risk-targeting and deterministic caps are applied, as a fraction of g. |
| `ssrt` | number | null | Risk-targeted probabilistic short-period spectral acceleration (SSUH x CRS), as a fraction of g. |
| `crs` | number | null | Risk coefficient applied at short periods to convert the uniform-hazard value to a risk-targeted one. |
| `ssd` | number | null | Deterministic short-period cap on SS, as a fraction of g. The mapped SS is the lesser of SSRT and SSD. |
| `s1uh` | number | null | Uniform-hazard 1-second spectral acceleration before risk-targeting and deterministic caps, as a fraction of g. |
| `s1rt` | number | null | Risk-targeted probabilistic 1-second spectral acceleration (S1UH x CR1), as a fraction of g. |
| `cr1` | number | null | Risk coefficient applied at a 1-second period. |
| `s1d` | number | null | Deterministic 1-second cap on S1, as a fraction of g. |
| `pgauh` | number | null | Uniform-hazard peak ground acceleration before deterministic capping, as a fraction of g. |
| `pgad` | number | null | Deterministic cap on the mapped peak ground acceleration, as a fraction of g. |

#### Response spectra

| Field | Type | Description |
|---|---|---|
| `spectrum_type` | string | null | Which response-spectrum method the edition uses: two-period (ASCE 7-05/7-10/7-16, the classic SDS/SD1 two-branch spectrum) or multi-period (ASCE 7-22 / NEHRP-2020, 22 tabulated periods). Null for ASCE 41. |
| `design_spectrum_periods_s` | array | null | Periods, in seconds, of the design response spectrum returned by the service. Pairs with design\_spectrum\_ordinates\_g index for index. Empty array when the service resolved the site but returned no spectrum (which is what a site-specific ASCE 7-16 result looks like). Null when includeSpectra was turned off. |
| `design_spectrum_ordinates_g` | array | null | Design spectral response accelerations, as fractions of g, at the matching periods in design\_spectrum\_periods\_s. This is the curve an engineer plots for a response-spectrum analysis. |
| `mcer_spectrum_periods_s` | array | null | Periods, in seconds, of the risk-targeted maximum considered earthquake (MCE\_R) response spectrum. |
| `mcer_spectrum_ordinates_g` | array | null | MCE\_R spectral response accelerations, as fractions of g, at the matching periods in mcer\_spectrum\_periods\_s. Nominally 1.5x the design ordinates. |
| `vertical_spectrum_points` | integer | null | Number of points in the vertical design response spectrum the service returned (ASCE 7-16 Sec. 11.9). 0 when the edition supports it but returned nothing for this site; null when the edition does not report one. |

#### ASCE 41-17 hazard levels (asce41-17 only)

| Field | Type | Description |
|---|---|---|
| `asce41_bse2n_sxs` | number | null | ASCE 41-17 short-period spectral acceleration parameter SXS at the BSE-2N hazard level, as a fraction of g. BSE-2N is the ASCE 41 Basic Safety Earthquake for new-building-equivalent Collapse Prevention and is numerically the MCE\_R. Populated only when referenceDocument is asce41-17. |
| `asce41_bse2n_sx1` | number | null | ASCE 41-17 1-second spectral acceleration parameter SX1 at the BSE-2N hazard level, as a fraction of g. Populated only when referenceDocument is asce41-17. |
| `asce41_bse1n_sxs` | number | null | ASCE 41-17 short-period spectral acceleration parameter SXS at the BSE-1N hazard level, as a fraction of g. BSE-1N is two thirds of BSE-2N and is the new-building-equivalent Life Safety level, numerically the ASCE 7 design level. Populated only when referenceDocument is asce41-17. |
| `asce41_bse1n_sx1` | number | null | ASCE 41-17 1-second spectral acceleration parameter SX1 at the BSE-1N hazard level, as a fraction of g. Populated only when referenceDocument is asce41-17. |
| `asce41_bse2e_sxs` | number | null | ASCE 41-17 short-period spectral acceleration parameter SXS at the BSE-2E hazard level, as a fraction of g. BSE-2E is the existing-building Basic Performance Objective Collapse Prevention level (5% in 50 years), capped at BSE-2N. Populated only when referenceDocument is asce41-17. |
| `asce41_bse2e_sx1` | number | null | ASCE 41-17 1-second spectral acceleration parameter SX1 at the BSE-2E hazard level, as a fraction of g. Populated only when referenceDocument is asce41-17. |
| `asce41_bse1e_sxs` | number | null | ASCE 41-17 short-period spectral acceleration parameter SXS at the BSE-1E hazard level, as a fraction of g. BSE-1E is the existing-building Basic Performance Objective Life Safety level (20% in 50 years), capped at BSE-1N. Populated only when referenceDocument is asce41-17. |
| `asce41_bse1e_sx1` | number | null | ASCE 41-17 1-second spectral acceleration parameter SX1 at the BSE-1E hazard level, as a fraction of g. Populated only when referenceDocument is asce41-17. |

#### ASCE 7-22 cross-check (current edition)

| Field | Type | Description |
|---|---|---|
| `asce722_status` | string | null | Outcome of the ASCE 7-22 (current edition) cross-check for this site. ok = the current-edition values on this row are real. not\_requested = includeCurrentEdition was turned off. not\_applicable = the primary lookup already IS ASCE 7-22, or is ASCE 41, or the primary lookup failed so no comparison is meaningful. no\_coverage = ASCE 7-22 has no data for this point. unavailable = the cross-check request failed. Every asce722\_\* value is null unless this reads ok. |
| `asce722_error` | string | null | Why the ASCE 7-22 cross-check did not complete. Null when it succeeded or was not attempted. |
| `asce722_ss` | number | null | Mapped MCE\_R short-period spectral response acceleration under ASCE 7-22, as a fraction of g. |
| `asce722_s1` | number | null | Mapped MCE\_R 1-second spectral response acceleration under ASCE 7-22, as a fraction of g. |
| `asce722_sds` | number | null | Design short-period spectral response acceleration under ASCE 7-22, the current edition referenced by IBC 2024. |
| `asce722_sd1` | number | null | Design 1-second spectral response acceleration under ASCE 7-22. ASCE 7-22 resolves many high-seismicity soft-soil sites that ASCE 7-16 left null under Sec. 11.4.8. |
| `asce722_sdc` | string | null | Seismic Design Category under ASCE 7-22. San Francisco Site Class D returns "D" here while ASCE 7-16 returns null. |
| `asce722_sms` | number | null | Site-modified MCE\_R short-period spectral response acceleration under ASCE 7-22. |
| `asce722_sm1` | number | null | Site-modified MCE\_R 1-second spectral response acceleration under ASCE 7-22. |
| `asce722_pgam` | number | null | Site-adjusted peak ground acceleration PGA\_M under ASCE 7-22, as a fraction of g. |
| `asce722_tl` | number | null | Long-period transition period under ASCE 7-22, in seconds. |
| `asce722_site_specific_study_required` | boolean | null | True when ASCE 7-22 also could not finalize SD1/SDC for this site. False when ASCE 7-22 resolved it - which is the common outcome for sites that ASCE 7-16 flagged. Null when the cross-check did not run. |
| `asce722_model_version` | string | null | USGS hazard model version behind the ASCE 7-22 values (v5.0.x), which is a different model from the v4.0.x behind ASCE 7-16. |
| `asce722_vs30_m_s` | number | null | The shear-wave velocity in the top 30 m that ASCE 7-22 assigned to the requested site class, in metres per second. ASCE 7-16 does not report this. |
| `asce722_source_url` | string | null | The exact USGS request URL used for the ASCE 7-22 cross-check. |
| `asce722_sdc_vs_primary` | string | null | How the ASCE 7-22 Seismic Design Category compares with the one from the selected edition: same, differs, primary\_unresolved (the selected edition returned no final SDC), unavailable, not\_requested or not\_applicable. Never reads same or differs unless BOTH editions finalized a category. |
| `current_edition_note` | string | null | Plain-language explanation of what this row says about the current standard - including the common case where the selected edition demanded a site-specific study but ASCE 7-22 resolves the site outright. Always populated on a resolved row. |

***

### How this actor fails

An actor that returns a confident wrong answer is worse than one that crashes: you get
billed, you act on it, and nobody reports a bug. So:

- **`null` means "not checked". `false` and `0` are answers.** Every row carries
  `primary_status` and `asce722_status`. A null SD1 with `primary_status: site_specific`
  is a real result about your site; a null SD1 with `primary_status: unavailable` is an
  outage, and the two are never rendered the same way.
- **The ASCE 7-22 comparison is gated.** `asce722_sdc_vs_primary` can only read `same` or
  `differs` when **both** editions finalized a category. If the cross-check failed it
  reads `unavailable` and no `asce722_*` value is populated.
- **A live drift check runs before your sites do.** Three canary points (San Francisco and
  Chicago under ASCE 7-16, San Francisco under ASCE 7-22) are probed first. If SDS or SS
  moves outside its expected band, if Chicago stops being SDC B, if a required key vanishes
  from the payload, or if USGS echoes back a **different reference document than the one
  requested**, the run fails before a single row is emitted. An offline test cannot catch a
  silently changed upstream - the fixture was captured from it.
- **If every site fails upstream, the run FAILS with zero rows.** A per-site screener that
  emits one error row per site on a total outage is billing you for rows that assert
  nothing. Invalid coordinates you supplied are different: those come back as `error` rows
  in a successful run, because that is information you need.
- **A payload that answers for the wrong edition never resolves.** It becomes an error row,
  not a design value.

### Pricing

**Pay per result: $6.00 per 1,000 rows** (about **$0.006 per site**), plus Apify platform
usage. One site = one row = one billable result, no matter how many editions are queried
for it - the ASCE 7-22 cross-check and the three upstream canary probes are free.
Graduated discounts apply on paid Apify plans.

### Use as an MCP tool

Every actor in this portfolio is exposed to AI agents through
[mcp.apify.com](https://mcp.apify.com). Agents read the input and output schemas directly,
so an assistant can be asked *"what Seismic Design Category applies to these twelve
candidate sites under the current code?"* and chain the answer into the next step. Field
descriptions are written for that purpose: each one says what the value means and when it
is null.

### FAQ

**Which edition should I use?**
Whichever your authority having jurisdiction has adopted. IBC 2024 references ASCE 7-22;
IBC 2018 and 2021 reference ASCE 7-16; IBC 2012/2015 reference ASCE 7-10. The default is
`asce7-16` and the ASCE 7-22 answer is added to every row regardless, so you can see both.

**Why is SD1 null for my California site?**
Under ASCE 7-16, Sec. 11.4.8 requires a site-specific ground-motion procedure for Site
Class D/E where S1 >= 0.2, and the service returns null rather than a value. Check
`asce722_sd1` and `asce722_sdc` on the same row - ASCE 7-22 usually resolves it. And check
`sdc_minimum`, which carries the short-period category as a hard lower bound.

**Should I use `pga` or `pgam`?**
`pgam` (PGA\_M) for anything geotechnical. ASCE 7 Sec. 11.8.3 liquefaction evaluation uses
the **site-adjusted** peak ground acceleration, which is `pgam` = `fpga` x `pga`. `pga`
alone is the mapped bedrock-reference value before the site coefficient.

**Does this replace a site-specific seismic hazard study?**
No. It returns exactly what the USGS national seismic hazard model gives for a coordinate
and a declared site class. It does not know your actual soil profile, nearby faults at
project scale, liquefaction susceptibility, or basin effects, and it produces nothing a
licensed engineer can seal.

**What site class should I use if I have no geotechnical report?**
D is the code default for unknown soil, and it is this actor's default. It is also the
class most likely to trigger the ASCE 7-16 site-specific rule in high-seismic areas. If
you have measured Vs30 or a boring log, set `siteClass` per site - it changes every number
on the row.

**How current is the data?**
The service is queried live on every run. `model_version` records which USGS national
seismic hazard model produced the values (v4.0.x for ASCE 7-16, v5.0.x for ASCE 7-22);
keep it with any value you archive.

**How many sites can I screen at once?**
Up to `maxAssets` (default 500, hard ceiling 5,000). Lookups run four at a time.

### Related actors

Seismic is one layer of a site screen. These cover the rest of the ground:

- **[USGS Bedrock Geology & Lithology Screener](https://apify.com/malonestar/usgs-bedrock-geology-lithology-screener)** - the rock and soil beneath the site, which is what drives site class.
- **[USGS Landslide Proximity Screener](https://apify.com/malonestar/usgs-landslide-proximity-screener)** - mapped landslides and slide-prone terrain, a common seismic secondary hazard.
- **[Karst & Sinkhole Risk Screener](https://apify.com/malonestar/karst-sinkhole-risk-screener)** - carbonate and evaporite karst, subsidence and collapse risk.
- **[FEMA NRI County Risk Profile](https://apify.com/malonestar/fema-nri-county-risk-profile)** - earthquake risk in the context of all 18 FEMA perils, at county and tract resolution.
- **[Site Due Diligence Bundle](https://apify.com/malonestar/site-due-diligence-bundle)** - 20 environmental, geological and regulatory layers for one coordinate in one call, including a seismic layer.

### Data source and disclaimer

Source: the **USGS ASCE 7 / ASCE 41 seismic design geodata web service**
(`earthquake.usgs.gov/ws/building-codes`, project `erp-design-ws`), a keyless public U.S.
Geological Survey service. Values are as published by USGS and are not modified.

This actor is an **informational screening aid**. It is not a stamped engineering
determination, not a site-specific ground-motion study, and not a substitute for review by
a licensed structural or geotechnical engineer. Nothing here should be used for
permitting, construction or life-safety decisions without that review. Not affiliated
with or endorsed by USGS, ASCE, or any code authority.

# Actor input Schema

## `assets` (type: `array`):

Coordinates to look up ASCE 7 seismic design parameters for. Each item is an object: {"lat": \<number -90..90>, "lon": \<number -180..180>, "label": "<your name for the site>", "riskCategory": "I|II|III|IV" (optional per-site override), "siteClass": "A|B|C|D|E" (optional per-site override)}. Each site produces exactly one billable dataset row regardless of how many editions are queried for it. Invalid points produce an ERROR row and the run continues; if EVERY site fails upstream the run is failed so nothing is billed.

## `riskCategory` (type: `string`):

ASCE 7 Risk Category applied to any site that does not set its own riskCategory. I = low hazard to human life, II = ordinary buildings, III = substantial hazard, IV = essential facilities (hospitals, fire stations). Default II.

## `siteClass` (type: `string`):

ASCE 7 Site Class (soil profile) applied to any site that does not set its own siteClass. A = hard rock, B = rock, C = very dense soil/soft rock, D = stiff soil, E = soft clay soil. D is the code default when the soil is unknown. Default D.

## `referenceDocument` (type: `string`):

Reference standard used for the ss/s1/sds/sd1/sdc columns. asce7-22 is the CURRENT edition (referenced by IBC 2024); asce7-16 remains the default so existing integrations keep the values they were built on, and an ASCE 7-22 cross-check is added to every row anyway in the asce722\_\* columns. asce7-10 and asce7-05 are for older permits; asce41-17 is seismic evaluation and retrofit of EXISTING buildings (BSE-2N/1N/2E/1E hazard levels, not SDS/SD1/SDC); nehrp-2015 and nehrp-2020 are the NEHRP provisions behind ASCE 7-16 and 7-22 respectively.

## `maxAssets` (type: `integer`):

Safety cap on the number of sites looked up per run. Sites beyond this cap are skipped with a warning.

## `includeCurrentEdition` (type: `boolean`):

ON by default. Adds a second lookup against ASCE 7-22, the current edition, and puts the result in the asce722\_\* columns alongside whichever edition you selected - so you can see where the two disagree. This matters: ASCE 7-16 returns no SD1 and no Seismic Design Category for high-seismicity soft-soil sites (Sec. 11.4.8), while ASCE 7-22 resolves most of them outright. San Francisco Site Class D is SDC null under 7-16 and SDC D under 7-22. Does NOT change your billing - still one row per site. Skipped automatically when the selected edition already is ASCE 7-22, or is ASCE 41-17.

## `includeSpectra` (type: `boolean`):

ON by default. Emits the full design and MCE\_R response-spectrum period/ordinate arrays that the USGS service already returns - the curve you plot for a response-spectrum analysis. Turn off for a narrower CSV export.

## `verifyUpstream` (type: `boolean`):

ON by default. Before any of your sites are screened, the run probes three known-good canary points (San Francisco and Chicago under ASCE 7-16, San Francisco under ASCE 7-22) and fails the whole run if the design values, the payload shape, or the edition echoed back have drifted. Costs three extra requests and protects you from being billed for values computed off a silently changed hazard model. Turn off only if you need the absolute lowest latency.

## Actor input object example

```json
{
  "assets": [
    {
      "lat": 37.7749,
      "lon": -122.4194,
      "label": "San Francisco, CA"
    },
    {
      "lat": 41.8781,
      "lon": -87.6298,
      "label": "Chicago, IL"
    },
    {
      "lat": 35.1495,
      "lon": -90.049,
      "label": "Memphis TN hospital (New Madrid, soft soil)",
      "riskCategory": "IV",
      "siteClass": "E"
    }
  ],
  "riskCategory": "II",
  "siteClass": "D",
  "referenceDocument": "asce7-16",
  "maxAssets": 500,
  "includeCurrentEdition": true,
  "includeSpectra": true,
  "verifyUpstream": true
}
```

# Actor output Schema

## `results` (type: `string`):

The default dataset with one seismic design row per site.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "assets": [
        {
            "lat": 37.7749,
            "lon": -122.4194,
            "label": "San Francisco, CA"
        },
        {
            "lat": 41.8781,
            "lon": -87.6298,
            "label": "Chicago, IL"
        },
        {
            "lat": 35.1495,
            "lon": -90.049,
            "label": "Memphis TN hospital (New Madrid, soft soil)",
            "riskCategory": "IV",
            "siteClass": "E"
        }
    ],
    "riskCategory": "II",
    "siteClass": "D",
    "referenceDocument": "asce7-16",
    "includeCurrentEdition": true,
    "includeSpectra": true,
    "verifyUpstream": true
};

// Run the Actor and wait for it to finish
const run = await client.actor("malonestar/usgs-seismic-design-screener").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "assets": [
        {
            "lat": 37.7749,
            "lon": -122.4194,
            "label": "San Francisco, CA",
        },
        {
            "lat": 41.8781,
            "lon": -87.6298,
            "label": "Chicago, IL",
        },
        {
            "lat": 35.1495,
            "lon": -90.049,
            "label": "Memphis TN hospital (New Madrid, soft soil)",
            "riskCategory": "IV",
            "siteClass": "E",
        },
    ],
    "riskCategory": "II",
    "siteClass": "D",
    "referenceDocument": "asce7-16",
    "includeCurrentEdition": True,
    "includeSpectra": True,
    "verifyUpstream": True,
}

# Run the Actor and wait for it to finish
run = client.actor("malonestar/usgs-seismic-design-screener").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "assets": [
    {
      "lat": 37.7749,
      "lon": -122.4194,
      "label": "San Francisco, CA"
    },
    {
      "lat": 41.8781,
      "lon": -87.6298,
      "label": "Chicago, IL"
    },
    {
      "lat": 35.1495,
      "lon": -90.049,
      "label": "Memphis TN hospital (New Madrid, soft soil)",
      "riskCategory": "IV",
      "siteClass": "E"
    }
  ],
  "riskCategory": "II",
  "siteClass": "D",
  "referenceDocument": "asce7-16",
  "includeCurrentEdition": true,
  "includeSpectra": true,
  "verifyUpstream": true
}' |
apify call malonestar/usgs-seismic-design-screener --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=malonestar/usgs-seismic-design-screener",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/1SfhSn5oeY2rKIonW/builds/GJZOeuh42dIA8CLeu/openapi.json