> ## Documentation Index
> Fetch the complete documentation index at: https://calcs.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# USGS API Solver

> Retrieve seismic design parameters from the USGS Seismic Web Services API

## Summary

This solver connects to the [USGS Seismic Web Services API](https://earthquake.usgs.gov/hazards/designmaps/) and returns seismic load parameters to be used in Calcs.com calculations.

<Note>
  Make sure that `enableTypes` is set to true for the unit awareness to work properly.
</Note>

## Inputs

| **Parameter**  | **Data Type** | **Units** | **Default** | **Description**                                                                       |
| -------------- | ------------- | --------- | ----------- | ------------------------------------------------------------------------------------- |
| `latitude`     | number        | deg       | -           | Latitude, in decimals (same format as `projectDefault("latitude")`)                   |
| `longitude`    | number        | deg       | -           | Longitude, in decimals (same format as `projectDefault("longitude")`)                 |
| `standard`     | string        | -         | -           | The standard to be used for the API. Currently, this solver only supports `ASCE 7-16` |
| `riskCategory` | string        | -         | -           | The Risk Category per ASCE 7. Can be one of "I", "II", "III", "IV"                    |
| `siteClass`    | string        | -         | -           | 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

<Accordion title="Direct USGS API 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]
</Accordion>

### Calculated Outputs

<Note>
  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.
</Note>

* **`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**.

<Warning>
  If the API fails, the solver will return the following data:

  ```json theme={null}
  {
      "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]"*
</Warning>

### Fallback Implementation

<Tip>
  **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.
</Tip>

## Implementation Example

<CodeBlock title="USGS API Solver Usage">
  ```javascript theme={null}
  {
      "type": "sheetTemplateWidgets",
      "attributes": {
          "type": "remote",
          "solver": "usgsSeismic",
          "equation": [
              {
                  "result": "SOLVER_INPUT_OBJECT",
                  "condition": "@default"
              }
          ],
          "referenceId": "seismic_data"
      }
  }
  ```
</CodeBlock>

<CodeBlock title="Solver Input Object">
  ```javascript theme={null}
  {
      latitude: projectDefault("latitude", 40.7128) deg,
      longitude: projectDefault("longitude", -74.0060) deg,
      standard: "ASCE 7-16",
      riskCategory: risk_cat,
      siteClass: site_class
  }
  ```
</CodeBlock>

## 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

<Note>
  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.
</Note>