promptadmin/drug-discovery-prompts
1
0
Fork 0
Code Issues Pull Requests 28 Packages Projects Releases Wiki Activity
Files
upstream-sync/scientific-agent-skills-20260818-9e8b0c-fcfk
drug-discovery-prompts/upstream/K-Dense-AI-scientific-agent-skills/skills/database-lookup/references/usgs.md
T

274 lines
9.9 KiB
Markdown
Raw Permalink Blame History

---
title: "USGS API Reference (Earthquake Hazards + Water Services)"
task: ""
lineage_type: import
upstream_source: https://github.com/K-Dense-AI/scientific-agent-skills/blob/9c9bd2e9/skills/database-lookup/references/usgs.md
upstream_sha: 9c9bd2e9
imported_at: 2026-06-26
prompt_class: prompt
upstream_changes: accepted
author: upstream
validated: false
---
# USGS API Reference (Earthquake Hazards + Water Services)
## Part A: Earthquake Hazards Program
### Base URL
```
https://earthquake.usgs.gov/fdsnws/event/1
```
### Authentication
**None required.** Fully public, no API key needed.
### Rate Limits
- No documented per-user rate limit, but USGS asks users to limit automated queries to avoid overloading the service.
- Requests returning very large result sets (>20,000 events) will be rejected. Use pagination or narrow your query.
### Key Endpoints
#### 1. Query Earthquakes
```
GET /query
```
Returns earthquake events matching search criteria. This is the primary endpoint.
**Parameters:**
| Parameter | Type | Required | Default | Description |
|--------------|--------|----------|------------|-------------|
| `format` | string | No | `quakeml` | `geojson`, `csv`, `quakeml`, `text`, `kml`. Use `geojson` for JSON. |
| `starttime` | string | No | (now - 30d)| ISO8601 date, e.g. `2024-01-01`. |
| `endtime` | string | No | (now) | ISO8601 date. |
| `minmagnitude`| float | No | - | Minimum magnitude (e.g. `4.5`). |
| `maxmagnitude`| float | No | - | Maximum magnitude. |
| `mindepth` | float | No | - | Minimum depth in km. |
| `maxdepth` | float | No | - | Maximum depth in km. |
| `latitude` | float | No | - | Center latitude for circle search (-90 to 90). |
| `longitude` | float | No | - | Center longitude for circle search (-180 to 180). |
| `maxradiuskm`| float | No | - | Max radius in km (with lat/lon). |
| `minlatitude`| float | No | - | Bounding box south edge. |
| `maxlatitude`| float | No | - | Bounding box north edge. |
| `minlongitude`| float | No | - | Bounding box west edge. |
| `maxlongitude`| float | No | - | Bounding box east edge. |
| `limit` | int | No | - | Max events returned (max 20000). |
| `offset` | int | No | 1 | Pagination offset (1-based). |
| `orderby` | string | No | `time` | `time`, `time-asc`, `magnitude`, `magnitude-asc`. |
| `alertlevel` | string | No | - | PAGER alert: `green`, `yellow`, `orange`, `red`. |
| `eventtype` | string | No | - | e.g. `earthquake`, `quarry blast`. |
**Example -- significant earthquakes in a region:**
```
https://earthquake.usgs.gov/fdsnws/event/1/query?format=geojson&starttime=2024-01-01&endtime=2024-12-31&minmagnitude=5.0&minlatitude=30&maxlatitude=45&minlongitude=-125&maxlongitude=-110&orderby=magnitude
```
**GeoJSON Response:**
```json
{
"type": "FeatureCollection",
"metadata": {
"generated": 1700000000000,
"url": "https://earthquake.usgs.gov/fdsnws/event/1/query?...",
"title": "USGS Earthquakes",
"status": 200,
"api": "1.14.1",
"count": 42
},
"features": [
{
"type": "Feature",
"properties": {
"mag": 6.2,
"place": "15 km NNE of Ridgecrest, CA",
"time": 1700000000000,
"updated": 1700100000000,
"tz": null,
"url": "https://earthquake.usgs.gov/earthquakes/eventpage/ci00000001",
"detail": "https://earthquake.usgs.gov/fdsnws/event/1/query?eventid=ci00000001&format=geojson",
"felt": 1500,
"cdi": 7.1,
"mmi": 6.5,
"alert": "yellow",
"status": "reviewed",
"tsunami": 0,
"sig": 800,
"net": "ci",
"code": "00000001",
"type": "earthquake",
"title": "M 6.2 - 15 km NNE of Ridgecrest, CA"
},
"geometry": {
"type": "Point",
"coordinates": [-117.5, 35.8, 10.5]
},
"id": "ci00000001"
}
]
}
```
Note: `geometry.coordinates` is `[longitude, latitude, depth_km]`.
#### 2. Event Detail
```
GET /query?eventid={EVENTID}&format=geojson
```
Returns detailed info for a single event, including moment tensor, focal mechanism, and nearby cities.
#### 3. Event Count
```
GET /count
```
Same parameters as `/query`, returns just the count of matching events. Useful for checking result size before querying.
**Example:**
```
https://earthquake.usgs.gov/fdsnws/event/1/count?starttime=2024-01-01&endtime=2024-12-31&minmagnitude=4.5
```
#### 4. Real-Time Feeds (no parameters)
Pre-built GeoJSON feeds updated every minute/5 min/15 min/hour:
```
https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/significant_month.geojson
https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/4.5_week.geojson
https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/2.5_day.geojson
https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_hour.geojson
```
Pattern: `{significance}_{timeperiod}.geojson` where significance is `significant`, `4.5`, `2.5`, `1.0`, `all` and timeperiod is `hour`, `day`, `week`, `month`.
---
## Part B: Water Services
### Base URL
```
https://waterservices.usgs.gov/nwis
```
### Authentication
**None required.** Fully public, no API key needed.
### Rate Limits
- No strict per-user limit, but USGS recommends limiting automated requests. Large queries may time out.
### Key Endpoints
#### 1. Instantaneous Values (Real-Time Data)
```
GET /iv/
```
Returns the most recent sensor readings (typically 15-minute intervals).
**Parameters:**
| Parameter | Type | Required | Default | Description |
|----------------|--------|----------|---------|-------------|
| `format` | string | No | `wml` | `json`, `xml`, `wml,1.1`, `wml,2.0`, `rdb`. Use `json` for JSON. |
| `sites` | string | Cond. | - | Comma-separated USGS site numbers (e.g. `01646500`). |
| `stateCd` | string | Cond. | - | 2-letter state code (e.g. `NY`). |
| `huc` | string | Cond. | - | Hydrologic Unit Code(s). |
| `bBox` | string | Cond. | - | Bounding box: `west,south,east,north` (decimal degrees). |
| `countyCd` | string | Cond. | - | 5-digit FIPS county code(s). |
| `parameterCd` | string | No | `00060` | Parameter code(s). `00060`=streamflow, `00065`=gage height, `00010`=water temp. |
| `period` | string | No | - | ISO8601 duration, e.g. `P7D` (past 7 days). |
| `startDT` | string | No | - | Start datetime (ISO8601). |
| `endDT` | string | No | - | End datetime (ISO8601). |
| `siteType` | string | No | - | e.g. `ST` (stream), `GW` (groundwater), `LK` (lake). |
| `siteStatus` | string | No | `all` | `active`, `inactive`, `all`. |
At least one location parameter (`sites`, `stateCd`, `huc`, `bBox`, or `countyCd`) is required.
**Example -- real-time streamflow for a site:**
```
https://waterservices.usgs.gov/nwis/iv/?format=json&sites=01646500&parameterCd=00060&period=P1D
```
**JSON Response (abbreviated):**
```json
{
"name": "ns1:timeSeriesResponseType",
"declaredType": "org.cuahsi.waterml.TimeSeriesResponseType",
"value": {
"timeSeries": [
{
"sourceInfo": {
"siteName": "Potomac River near Wash, DC Little Falls Pump Sta",
"siteCode": [{"value": "01646500", "agencyCode": "USGS"}],
"geoLocation": {
"geogLocation": {"latitude": 38.94977778, "longitude": -77.12763889}
}
},
"variable": {
"variableCode": [{"value": "00060"}],
"variableName": "Streamflow, ft³/s",
"unit": {"unitCode": "ft3/s"}
},
"values": [
{
"value": [
{"value": "5280", "dateTime": "2024-01-15T00:00:00.000-05:00"},
{"value": "5310", "dateTime": "2024-01-15T00:15:00.000-05:00"}
]
}
]
}
]
}
}
```
#### 2. Daily Values (Historical Aggregates)
```
GET /dv/
```
Returns daily statistical values (mean, max, min). Same location parameters as `/iv/`.
**Additional Parameters:**
| Parameter | Type | Description |
|-----------|--------|-------------|
| `statCd` | string | Statistic code: `00001`=max, `00002`=min, `00003`=mean, `00006`=sum. Default `00003`. |
**Example -- daily mean streamflow, 1 year:**
```
https://waterservices.usgs.gov/nwis/dv/?format=json&sites=01646500&parameterCd=00060&statCd=00003&startDT=2023-01-01&endDT=2023-12-31
```
#### 3. Site Information
```
GET /site/
```
Returns metadata about monitoring sites. Same location parameters apply.
**Example -- active stream sites in Virginia:**
```
https://waterservices.usgs.gov/nwis/site/?format=rdb&stateCd=VA&siteType=ST&siteStatus=active&hasDataTypeCd=iv
```
#### 4. Statistics (Pre-computed)
```
GET /stat/
```
Returns pre-computed statistics (percentiles, mean, median) for daily values, useful for comparing current conditions to historical norms.
**Example:**
```
https://waterservices.usgs.gov/nwis/stat/?format=rdb&sites=01646500&parameterCd=00060&statReportType=daily&statTypeCd=mean,p05,p25,p50,p75,p95
```
### Common Parameter Codes
| Code | Description |
|---------|-------------|
| `00060` | Discharge/streamflow (ft3/s) |
| `00065` | Gage height (ft) |
| `00010` | Water temperature (C) |
| `00045` | Precipitation (in) |
| `00400` | pH |
| `00300` | Dissolved oxygen (mg/L) |
| `00095` | Specific conductance (uS/cm) |
| `72019` | Groundwater level depth below land surface (ft) |
## Notes
- Earthquake API returns coordinates as `[lon, lat, depth]` (note: longitude first).
- Water Services JSON wraps data in a verbose WaterML-like structure. The `rdb` (tab-delimited) format is simpler for tabular data.
- USGS site numbers are typically 8 digits for surface water, 15 for groundwater.
- Both APIs are free, public, and require no authentication.
Reference in New Issue View Git Blame Copy Permalink