API Documentation - Earthquake Catalog

This is an implementation of the FDSN Event Web Service Specification, and allows custom searches for earthquake information using a variety of parameters.

Please note that automated applications should use Real-time GeoJSON Feeds for displaying earthquake information whenever possible, as they will have the best performance and availability for that type of information.

URL

https://earthquake.usgs.gov/fdsnws/event/1/[METHOD[?PARAMETERS]]

Methods

application.json

request known enumerated parameter values for the interface.

https://earthquake.usgs.gov/fdsnws/event/1/application.json

application.wadl

request WADL for the interface.

https://earthquake.usgs.gov/fdsnws/event/1/application.wadl

catalogs

request available catalogs.

https://earthquake.usgs.gov/fdsnws/event/1/catalogs

contributors

request available contributors

https://earthquake.usgs.gov/fdsnws/event/1/contributors

count

to perform a count on a data request. Count uses the same parameters as the query method, and is availablein these formats: plain text (default), geojson, and xml.

query

to submit a data request. See the parameters section for supported url parameters.

version

request full service version number

https://earthquake.usgs.gov/fdsnws/event/1/version

Query method Parameters

These parameters should be submitted as key=value pairs using the HTTP GET method and may not be specified more than once; if a parameter is submitted multiple times the result is undefined.

Formats

If no format is specified quakeml will be returned by default.

parameter	type	default	description
`format`	String	quakeml	Specify the output format. `format=csv` Response format is CSV. Mime-type is “text/csv”. `format=geojson` Response format is GeoJSON. Mime-type is “application/json”. `format=kml` Response format is KML. Mime-type is “vnd.google-earth.kml+xml”. `format=quakeml` Alias for "xml" format. `format=text` Response format is plain text. Mime-type is “text/plain”. `format=xml` The xml format is dependent upon the request method used.

format=geojson

When format=geojson is defined there are additional parameters that can be specified that control how the geojson output is generated. The additional web service parameters are:

callback
jsonerror

format=kml

When format=kml is defined there are additional parameters that can be specified that control how the KML output is generated. The additional web service parameters are:

kmlanimated
kmlcolorby

format=text

This format is only available for the count, query, and version methods.

format=xml

The xml format is dependent upon the request method used.

method=query
Response format is Quakeml 1.2. Mime-type is "application/xml".
method=count
Response format is xml. Mime-type is “application/xml”.

Time

All times use ISO8601 Date/Time format. Unless a timezone is specified, UTC is assumed. Examples:

2024-11-22, Implicit UTC timezone, and time at start of the day (00:00:00)
2024-11-22T20:30:52, Implicit UTC timezone.
2024-11-22T20:30:52+00:00, Explicit timezone.

parameter	type	default	description
`endtime`	String	present time	Limit to events on or before the specified end time. NOTE: All times use ISO8601 Date/Time format. Unless a timezone is specified, UTC is assumed.
`starttime`	String	NOW - 30 days	Limit to events on or after the specified start time. NOTE: All times use ISO8601 Date/Time format. Unless a timezone is specified, UTC is assumed.
`updatedafter`	String	null	Limit to events updated after the specified time. NOTE: All times use ISO8601 Date/Time format. Unless a timezone is specified, UTC is assumed.

Location

Requests that use both rectangle and circle will return the intersection, which may be empty, use with caution.

Rectangle

Requests may use any combination of these parameters.

parameter	type	default	description
`minlatitude`	Decimal [-90,90] degrees	-90	Limit to events with a latitude larger than the specified minimum. NOTE: min values must be less than max values.
`minlongitude`	Decimal [-360,360] degrees	-180	Limit to events with a longitude larger than the specified minimum. NOTE: rectangles may cross the date line by using a minlongitude < -180 or maxlongitude > 180. NOTE: min values must be less than max values.
`maxlatitude`	Decimal [-90,90] degrees	90	Limit to events with a latitude smaller than the specified maximum. NOTE: min values must be less than max values.
`maxlongitude`	Decimal [-360,360] degrees	180	Limit to events with a longitude smaller than the specified maximum. NOTE: rectangles may cross the date line by using a minlongitude < -180 or maxlongitude > 180. NOTE: min values must be less than max values.

Circle

Requests must include all of latitude, longitude, and maxradius to perform a circle search.

parameter	type	default	description
`latitude`	Decimal [-90,90] degrees	null	Specify the latitude to be used for a radius search.
`longitude`	Decimal [-180,180] degrees	null	Specify the longitude to be used for a radius search.
`maxradius`	Decimal [0, 180] degrees	180	Limit to events within the specified maximum number of degrees from the geographic point defined by the latitude and longitude parameters. NOTE: This option is mutually exclusive with maxradiuskm and specifying both will result in an error.
`maxradiuskm`	Decimal [0, 20001.6] km	20001.6	Limit to events within the specified maximum number of kilometers from the geographic point defined by the latitude and longitude parameters. NOTE: This option is mutually exclusive with maxradius and specifying both will result in an error.

Other

parameter	type	default	description
`catalog`	String	null	Limit to events from a specified catalog. Use the Catalogs Method to find available catalogs. NOTE: when catalog and contributor are omitted, the most preferred information from any catalog or contributor for the event is returned.
`contributor`	String	null	Limit to events contributed by a specified contributor. Use the Contributors Method to find available contributors. NOTE: when catalog and contributor are omitted, the most preferred information from any catalog or contributor for the event is returned.
`eventid`	String	null	Select a specific event by ID; event identifiers are data center specific. NOTE: Selecting a specific event implies includeallorigins, includeallmagnitudes, and, additionally, associated moment tensor and focal-mechanisms are included.
`includeallmagnitudes`	Boolean	false	Specify if all magnitudes for the event should be included, default is data center dependent but is suggested to be the preferred magnitude only. NOTE: because magnitudes and origins are strongly associated, this parameter is interchangeable with includeallmagnitudes
`includeallorigins`	Boolean	false	Specify if all origins for the event should be included, default is data center dependent but is suggested to be the preferred origin only. NOTE: because magnitudes and origins are strongly associated, this parameter is interchangable with includeallmagnitudes
`includearrivals`	Boolean	false	Specify if phase arrivals should be included. NOTE: NOT CURRENTLY IMPLEMENTED
`includedeleted`	Boolean, or "only"	false	Specify if deleted products and events should be included. The value `only` returns only deleted events. Deleted events otherwise return the HTTP status `409 Conflict`. NOTE: Only supported by the `csv` and `geojson` formats, which include `status`.
`includesuperseded`	Boolean	false	Specify if superseded products should be included. This also includes all deleted products, and is mutually exclusive to the includedeleted parameter. NOTE: Only works when specifying eventid parameter.
`limit`	Integer [1,20000]	null	Limit the results to the specified number of events. NOTE: The service limits queries to 20000, and any that exceed this limit will generate a HTTP response code “400 Bad Request”.
`maxdepth`	Decimal [-100, 1000] km	1000	Limit to events with depth less than the specified maximum.
`maxmagnitude`	Decimal	null	Limit to events with a magnitude smaller than the specified maximum.
`mindepth`	Decimal [-100, 1000] km	-100	Limit to events with depth more than the specified minimum.
`minmagnitude`	Decimal	null	Limit to events with a magnitude larger than the specified minimum.
`offset`	Integer[1,∞]	1	Return results starting at the event count specified, starting at 1.
`orderby`	String	time	Order the results. The allowed values are: `orderby=time` order by origin descending time `orderby=time-asc` order by origin ascending time `orderby=magnitude` order by descending magnitude `orderby=magnitude-asc` order by ascending magnitude

Extensions

parameter	type	default	description
`alertlevel`	String	null	Limit to events with a specific PAGER alert level. The allowed values are: `alertlevel=green` Limit to events with PAGER alert level "green". `alertlevel=yellow` Limit to events with PAGER alert level "yellow". `alertlevel=orange` Limit to events with PAGER alert level "orange". `alertlevel=red` Limit to events with PAGER alert level "red".
`callback`	String	null	Convert GeoJSON output to a JSONP response using this callback. Mime-type is “text/javascript”. Callback values are restricted to the characters `[A-Za-z0-9\._]+` NOTE: Must be used with format=geojson
`eventtype`	String	null	Limit to events of a specific type. NOTE: “earthquake” will filter non-earthquake events.
`jsonerror`	Boolean	false	Request JSON(P) formatted output even on API error results. NOTE: Must be used with format=geojson
`kmlanimated`	Boolean	false	Whether to include timestamp in generated kml, for google earth animation support. NOTE: Must be used with format=kml
`kmlcolorby`	String	age	How earthquakes are colored. Accepted values are: `kmlcolorby=age` Color events in KML by age. `kmlcolorby=depth` Color events in KML by depth. NOTE: Must be used with format=kml
`maxcdi`	Decimal [0,12]	null	Maximum value for Maximum Community Determined Intensity reported by DYFI.
`maxgap`	Decimal [0,360] degrees	null	Limit to events with no more than this azimuthal gap.
`maxmmi`	Decimal [0,12]	null	Maximum value for Maximum Modified Mercalli Intensity reported by ShakeMap.
`maxsig`	Integer	null	Limit to events with no more than this significance.
`mincdi`	Decimal	null	Minimum value for Maximum Community Determined Intensity reported by DYFI.
`minfelt`	Integer[1,∞]	null	Limit to events with this many DYFI responses.
`mingap`	Decimal[0,360] degrees	null	Limit to events with no less than this azimuthal gap.
`minsig`	Integer	null	Limit to events with no less than this significance.
`nodata`	Integer (204\|404)	204	Define the error code that will be returned when no data is found.
`producttype`	String	null	Limit to events that have this type of product associated. Example producttypes: moment-tensor focal-mechanism shakemap losspager dyfi
`productcode`	String	null	Return the event that is associated with the productcode. The event will be returned even if the productcode is not the preferred code for the event. Example productcodes: nn00458749 at00ndf1fr
`reviewstatus`	String	all	Limit to events with a specific review status. The different review statuses are: `reviewstatus=automatic` Limit to events with review status "automatic". `reviewstatus=reviewed` Limit to events with review status "reviewed".