Skip to main content

​
Summary

This solver connects to the USGS Seismic Web Services API and returns seismic load parameters to be used in ClearCalcs calculations.
Make sure that enableTypes is set to true for the unit awareness to work properly.

​
Inputs

ParameterData TypeUnitsDefaultDescription
latitudenumberdeg-Latitude, in decimals (same format as projectDefault("latitude"))
longitudenumberdeg-Longitude, in decimals (same format as projectDefault("longitude"))
standardstring--The standard to be used for the API. Currently, this solver only supports ASCE 7-16
riskCategorystring--The Risk Category per ASCE 7. Can be one of “I”, “II”, “III”, “IV”
siteClassstring--The site class per ASCE 7. Possible values vary by the standard edition.

​
Site Class Options

For ASCE 7-16, siteClass can be one of:
  • A
  • B
  • B-estimated
  • C
  • D-default
  • D
  • E

​
Outputs

These are accessed with dot notation. For example, if the solver is in a widget with referenceId usgs_remote, the short-period ground acceleration would be accessed with usgs_remote.Ss.

​
Raw Map Outputs

  • Ss: The short-period ground acceleration (e.g. 0.65) [unitless]
  • S1: The 1s-period ground acceleration (e.g. 1.04) [unitless]
  • TL: The long-period transition period in seconds (e.g. 8 seconds) [in seconds]

​
Calculated Outputs

These are outputs that require some calculations per the code. We generally should have these calculations done in the calculator itself, but in cases like project defaults or shear walls, which require only a very specific output, we may choose to use these.
  • Sds: The short-period design acceleration [unitless]
  • sdc: The seismic design category

​
Error Handling

​
API Failure Response

Using an external API exposes us to a risk that the API becomes unavailable. We need to make sure that if it happens, our users won’t be blocked from running their calculations.
If the API fails, the solver will return the following data:
{
    "Ss": 0.0, 
    "S1": 0.0, 
    "TL": "0.0 s", 
    "Sds": 0.0, 
    "SDC": "None"
}
And give the following warning: “Error connecting to USGS server for seismic parameters. This is likely a problem with the USGS website. All parameters are currently taken as zero. These can be manually entered by turning off the “Automatic Seismic Loads?” option. Status code: [response.status_code]“

​
Fallback Implementation

Important: Our users need to be able to easily switch to manual load inputs and not run into any further issues if this happens. This is done at a template level in the implementation - it should be a clear “Automatic Seismic Loads?” Yes/No toggle.

​
Implementation Example

{
    "type": "sheetTemplateWidgets",
    "attributes": {
        "type": "remote",
        "solver": "usgsSeismic",
        "equation": [
            {
                "result": "SOLVER_INPUT_OBJECT",
                "condition": "@default"
            }
        ],
        "referenceId": "seismic_data"
    }
}

{
    latitude: projectDefault("latitude", 40.7128) deg,
    longitude: projectDefault("longitude", -74.0060) deg,
    standard: "ASCE 7-16",
    riskCategory: risk_cat,
    siteClass: site_class
}

​
Best Practices

  1. Always provide fallbacks: Implement manual input options for when the API is unavailable
  2. Use project defaults: Leverage projectDefault() functions for coordinates when possible
  3. Validate inputs: Ensure risk category and site class inputs are valid for the selected standard
  4. Handle errors gracefully: Design your template to continue functioning even when seismic data returns zeros
The USGS API provides authoritative seismic design parameters for locations within the United States. For international projects, alternative seismic data sources or manual input methods should be used.
⌘I