USGS API Reference (Earthquake Hazards + Water Services)

Part A: Earthquake Hazards Program

Water Services migration

USGS announces that WaterServices will be decommissioned in early 2027. The NWIS examples below target the legacy service. For new water-data applications, use https://api.waterdata.usgs.gov and its documented collections; do not translate NWIS query parameters mechanically. Earthquake APIs have a separate lifecycle. Source: https://waterservices.usgs.gov/

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:

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:

{
  "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:

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):

{
  "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:

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

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.