openapi: 3.0.3
info:
title: USGS Earthquake Notifications, Feeds, and Web Services Catalog Earthquakes API
description: The USGS Earthquake Hazards Program provides real-time earthquake data through the FDSN (International Federation of Digital Seismograph Networks) Event Web Service. This API allows searching the USGS ANSS (Advanced National Seismic System) ComCat earthquake catalog for event data using geographic, temporal, magnitude, and other filters. Responses are available in GeoJSON, CSV, KML, QuakeML, and text formats.
version: '1.0'
contact:
name: USGS Earthquake Hazards Program
url: https://earthquake.usgs.gov/
email: shake-admin@usgs.gov
license:
name: Public Domain (U.S. Government Work)
url: https://www.usgs.gov/information-policies-and-instructions/copyrights-and-credits
x-generated-from: documentation
servers:
- url: https://earthquake.usgs.gov/fdsnws/event/1
description: USGS FDSN Event Web Service
tags:
- name: Earthquakes
description: Query and retrieve earthquake event data from the USGS earthquake catalog.
paths:
/query:
get:
operationId: queryEarthquakes
summary: USGS Query Earthquake Events
description: Search the USGS earthquake catalog using geographic, temporal, magnitude, depth, and other filters. Returns earthquake events in the requested format (GeoJSON by default). Supports both rectangle and circle spatial filters, with a maximum of 20,000 events per request.
tags:
- Earthquakes
parameters:
- name: format
in: query
required: false
description: 'Response format. Options: geojson (default), csv, kml, quakeml, text, xml.'
schema:
type: string
enum:
- geojson
- csv
- kml
- quakeml
- text
- xml
default: geojson
example: geojson
- name: starttime
in: query
required: false
description: 'Limit events to those occurring after this time. ISO8601 format. Default: NOW minus 30 days.'
schema:
type: string
format: date-time
example: '2025-01-01T00:00:00Z'
- name: endtime
in: query
required: false
description: 'Limit events to those occurring before this time. ISO8601 format. Default: present.'
schema:
type: string
format: date-time
example: '2025-01-31T23:59:59Z'
- name: updatedafter
in: query
required: false
description: Return events updated after this ISO8601 timestamp.
schema:
type: string
format: date-time
- name: minlatitude
in: query
required: false
description: Minimum latitude for rectangle filter in degrees (-90 to 90).
schema:
type: number
format: float
minimum: -90
maximum: 90
example: 25.0
- name: maxlatitude
in: query
required: false
description: Maximum latitude for rectangle filter in degrees (-90 to 90).
schema:
type: number
format: float
minimum: -90
maximum: 90
example: 50.0
- name: minlongitude
in: query
required: false
description: Minimum longitude for rectangle filter in degrees (-360 to 360).
schema:
type: number
format: float
minimum: -360
maximum: 360
example: -125.0
- name: maxlongitude
in: query
required: false
description: Maximum longitude for rectangle filter in degrees (-360 to 360).
schema:
type: number
format: float
minimum: -360
maximum: 360
example: -65.0
- name: latitude
in: query
required: false
description: Latitude for circle filter center in degrees (-90 to 90).
schema:
type: number
format: float
minimum: -90
maximum: 90
example: 37.75
- name: longitude
in: query
required: false
description: Longitude for circle filter center in degrees (-360 to 360).
schema:
type: number
format: float
minimum: -360
maximum: 360
example: -122.0
- name: maxradius
in: query
required: false
description: Maximum search radius for circle filter in degrees (0 to 180).
schema:
type: number
format: float
minimum: 0
maximum: 180
example: 5.0
- name: maxradiuskm
in: query
required: false
description: Maximum search radius for circle filter in kilometers (0 to 20001.6).
schema:
type: number
format: float
minimum: 0
maximum: 20001.6
example: 100.0
- name: minmagnitude
in: query
required: false
description: Minimum earthquake magnitude.
schema:
type: number
format: float
example: 2.5
- name: maxmagnitude
in: query
required: false
description: Maximum earthquake magnitude.
schema:
type: number
format: float
example: 8.0
- name: mindepth
in: query
required: false
description: Minimum event depth in kilometers (-100 to 1000).
schema:
type: number
format: float
minimum: -100
maximum: 1000
example: 0.0
- name: maxdepth
in: query
required: false
description: Maximum event depth in kilometers (-100 to 1000).
schema:
type: number
format: float
minimum: -100
maximum: 1000
example: 700.0
- name: eventid
in: query
required: false
description: Retrieve a specific event by its USGS event identifier.
schema:
type: string
example: us7000n5no
- name: limit
in: query
required: false
description: Maximum number of events to return (1 to 20000).
schema:
type: integer
minimum: 1
maximum: 20000
example: 100
- name: offset
in: query
required: false
description: Starting record number for paginated results (1-based).
schema:
type: integer
minimum: 1
example: 1
- name: orderby
in: query
required: false
description: Order results by time, time-asc, magnitude, or magnitude-asc.
schema:
type: string
enum:
- time
- time-asc
- magnitude
- magnitude-asc
default: time
example: time
- name: catalog
in: query
required: false
description: Filter by earthquake catalog (e.g., us, ci, nc).
schema:
type: string
example: us
- name: contributor
in: query
required: false
description: Filter by contributing network.
schema:
type: string
example: us
- name: eventtype
in: query
required: false
description: Filter by event type (earthquake, explosion, quarry blast, etc.).
schema:
type: string
example: earthquake
- name: alertlevel
in: query
required: false
description: Filter by PAGER alert level (green, yellow, orange, red).
schema:
type: string
enum:
- green
- yellow
- orange
- red
example: yellow
- name: minsig
in: query
required: false
description: Minimum significance value (integer, 0+).
schema:
type: integer
minimum: 0
example: 100
- name: maxsig
in: query
required: false
description: Maximum significance value.
schema:
type: integer
minimum: 0
example: 1000
- name: reviewstatus
in: query
required: false
description: Filter by review status (automatic or reviewed).
schema:
type: string
enum:
- automatic
- reviewed
example: reviewed
- name: producttype
in: query
required: false
description: Filter by product type associated with the event (moment-tensor, focal-mechanism, shakemap, losspager, dyfi).
schema:
type: string
example: shakemap
- name: includedeleted
in: query
required: false
description: Include deleted events in results (true, false, or only).
schema:
type: string
enum:
- 'true'
- 'false'
- only
example: 'false'
- name: includeallorigins
in: query
required: false
description: Include all origin solutions in results.
schema:
type: boolean
example: false
- name: includeallmagnitudes
in: query
required: false
description: Include all magnitude estimates in results.
schema:
type: boolean
example: false
- name: nodata
in: query
required: false
description: HTTP status code to return when no data is found (204 or 404).
schema:
type: integer
enum:
- 204
- 404
example: 204
responses:
'200':
description: Successful response with earthquake event data.
content:
application/json:
schema:
$ref: '#/components/schemas/EarthquakeFeatureCollection'
examples:
QueryEarthquakes200Example:
summary: Default queryEarthquakes 200 response
x-microcks-default: true
value:
type: FeatureCollection
metadata:
generated: 1743897600000
url: https://earthquake.usgs.gov/fdsnws/event/1/query?format=geojson&limit=1
title: USGS Earthquakes
status: 200
api: 1.14.1
count: 1
features:
- type: Feature
properties:
mag: 4.5
place: 45 km NE of San Francisco, CA
time: 1743840000000
updated: 1743843600000
tz: null
url: https://earthquake.usgs.gov/earthquakes/eventpage/us7000n5no
detail: https://earthquake.usgs.gov/fdsnws/event/1/query?eventid=us7000n5no&format=geojson
felt: null
cdi: null
mmi: 3.2
alert: null
status: reviewed
tsunami: 0
sig: 312
net: us
code: 7000n5no
ids: ',us7000n5no,'
sources: ',us,'
types: ',origin,phase-data,'
nst: 45
dmin: 0.82
rms: 0.45
gap: 78
magType: mb
type: earthquake
title: M 4.5 - 45 km NE of San Francisco, CA
geometry:
type: Point
coordinates:
- -122.0
- 37.75
- 10.5
id: us7000n5no
'204':
description: No events found matching the query parameters.
'400':
description: Invalid request parameters.
content:
text/plain:
schema:
type: string
'404':
description: No data found (when nodata=404).
content:
text/plain:
schema:
type: string
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/count:
get:
operationId: countEarthquakes
summary: USGS Count Earthquake Events
description: Return the number of earthquake events matching the query parameters without returning event data. Accepts the same parameters as the query endpoint.
tags:
- Earthquakes
parameters:
- name: format
in: query
required: false
description: Response format (geojson or text).
schema:
type: string
enum:
- geojson
- text
default: geojson
- name: starttime
in: query
required: false
description: Start time in ISO8601 format.
schema:
type: string
format: date-time
example: '2025-01-01T00:00:00Z'
- name: endtime
in: query
required: false
description: End time in ISO8601 format.
schema:
type: string
format: date-time
example: '2025-01-31T23:59:59Z'
- name: minmagnitude
in: query
required: false
description: Minimum earthquake magnitude.
schema:
type: number
format: float
example: 5.0
- name: maxmagnitude
in: query
required: false
description: Maximum earthquake magnitude.
schema:
type: number
format: float
example: 9.0
- name: minlatitude
in: query
required: false
description: Minimum latitude for rectangle filter.
schema:
type: number
format: float
- name: maxlatitude
in: query
required: false
description: Maximum latitude for rectangle filter.
schema:
type: number
format: float
- name: minlongitude
in: query
required: false
description: Minimum longitude for rectangle filter.
schema:
type: number
format: float
- name: maxlongitude
in: query
required: false
description: Maximum longitude for rectangle filter.
schema:
type: number
format: float
responses:
'200':
description: Count of matching earthquake events.
content:
application/json:
schema:
$ref: '#/components/schemas/CountResponse'
examples:
CountEarthquakes200Example:
summary: Default countEarthquakes 200 response
x-microcks-default: true
value:
count: 1547
maxAllowed: 20000
'400':
description: Invalid request parameters.
content:
text/plain:
schema:
type: string
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
schemas:
EarthquakeFeature:
title: EarthquakeFeature
type: object
description: A GeoJSON Feature representing a single earthquake event.
properties:
type:
type: string
description: GeoJSON object type (always Feature).
example: Feature
properties:
$ref: '#/components/schemas/EarthquakeProperties'
geometry:
$ref: '#/components/schemas/EarthquakeGeometry'
id:
type: string
description: Unique USGS event identifier.
example: us7000n5no
CountResponse:
title: CountResponse
type: object
description: Response from the count endpoint.
properties:
count:
type: integer
description: Number of events matching the query.
example: 1547
maxAllowed:
type: integer
description: Maximum allowed events per query.
example: 20000
EarthquakeFeatureCollection:
title: EarthquakeFeatureCollection
type: object
description: GeoJSON FeatureCollection containing earthquake event records from the USGS ComCat earthquake catalog.
properties:
type:
type: string
description: GeoJSON object type (always FeatureCollection).
example: FeatureCollection
metadata:
$ref: '#/components/schemas/EarthquakeMetadata'
features:
type: array
description: Array of earthquake event GeoJSON Features.
items:
$ref: '#/components/schemas/EarthquakeFeature'
bbox:
type: array
description: Bounding box for the collection [min_lon, min_lat, max_lon, max_lat].
items:
type: number
example:
- -180.0
- -90.0
- 180.0
- 90.0
EarthquakeGeometry:
title: EarthquakeGeometry
type: object
description: GeoJSON Point geometry for the earthquake epicenter location.
properties:
type:
type: string
description: GeoJSON geometry type (always Point).
example: Point
coordinates:
type: array
description: Array of [longitude, latitude, depth_km]. Depth is in kilometers below the surface (positive = deeper).
items:
type: number
example:
- -122.0
- 37.75
- 10.5
EarthquakeProperties:
title: EarthquakeProperties
type: object
description: Properties of an earthquake event including magnitude, location, and metadata.
properties:
mag:
type: number
description: Earthquake magnitude.
example: 4.5
place:
type: string
description: Textual description of the event location.
example: 45 km NE of San Francisco, CA
time:
type: integer
description: Unix timestamp (milliseconds) of the earthquake occurrence.
example: 1743840000000
updated:
type: integer
description: Unix timestamp (milliseconds) of the last catalog update.
example: 1743843600000
url:
type: string
description: USGS event detail page URL.
example: https://earthquake.usgs.gov/earthquakes/eventpage/us7000n5no
detail:
type: string
description: API URL for the full event GeoJSON.
example: https://earthquake.usgs.gov/fdsnws/event/1/query?eventid=us7000n5no&format=geojson
felt:
type: integer
description: Number of DYFI (Did You Feel It?) responses.
example: 23
cdi:
type: number
description: Maximum Community Determined Intensity (CDI) value.
example: 3.5
mmi:
type: number
description: Maximum Modified Mercalli Intensity (MMI) from ShakeMap.
example: 3.2
alert:
type: string
description: PAGER alert level (green, yellow, orange, red).
example: green
status:
type: string
description: Review status (automatic or reviewed).
example: reviewed
tsunami:
type: integer
description: Tsunami hazard flag. 1 if tsunami warning was issued; 0 otherwise.
example: 0
sig:
type: integer
description: Significance value (0-1000) indicating event importance based on magnitude, MMI, felt reports, and estimated impact.
example: 312
net:
type: string
description: Network ID for the preferred source of event data.
example: us
code:
type: string
description: Event code assigned by the network.
example: 7000n5no
magType:
type: string
description: Magnitude type (ml, md, mb, mw, mww, etc.).
example: mb
type:
type: string
description: Event type (earthquake, explosion, quarry blast, etc.).
example: earthquake
title:
type: string
description: Title string summarizing the event.
example: M 4.5 - 45 km NE of San Francisco, CA
gap:
type: number
description: Azimuthal gap in degrees between seismic stations.
example: 78
dmin:
type: number
description: Horizontal distance from epicenter to nearest station in degrees.
example: 0.82
rms:
type: number
description: Root-mean-square travel time residual in seconds.
example: 0.45
nst:
type: integer
description: Number of seismic stations used to determine earthquake location.
example: 45
EarthquakeMetadata:
title: EarthquakeMetadata
type: object
description: Metadata about the earthquake query response.
properties:
generated:
type: integer
description: Unix timestamp (milliseconds) when the response was generated.
example: 1743897600000
url:
type: string
description: URL used to generate this response.
example: https://earthquake.usgs.gov/fdsnws/event/1/query?format=geojson&limit=10
title:
type: string
description: Title for this result set.
example: USGS Earthquakes
status:
type: integer
description: HTTP status code.
example: 200
api:
type: string
description: API version string.
example: 1.14.1
count:
type: integer
description: Number of events returned.
example: 47
limit:
type: integer
description: Maximum events requested.
example: 100
offset:
type: integer
description: Starting offset in the result set.
example: 1