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.
application.wadl
request WADL for the interface.
catalogs
request available catalogs.
contributors
request available 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

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:

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:

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.

Time

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

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