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