Earthquake Search and Web Service API Documentation

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.

FDSN Web Service Specification PDF.

URL

http://comcat.cr.usgs.gov/fdsnws/event/1/[METHOD[?PARAMETERS]]

Methods

query
to submit a data request.

See the Parameters section for supported url parameters.

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 available in these formats: plain text (default), geojson, and xml.

version
request full service version number.
application.wadl
request WADL for the interface.
application.json
request known enumerated parameter values for the interface.

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.

Time

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

2014-09-22
Implicity UTC timezone, and time at start of the day (00:00:00)
2014-09-22T04:13:13
Implicit UTC timezone.
2014-09-22T04:13:13+00:00
Explicit timezone.
starttime
ISO8601 Date/Time, e.g. 2014-09-22T04:13:13
Default is NOW-30 days
Limit to events on or after the specified start time.
endtime
ISO8601 Date/Time, e.g. 2014-09-22T04:13:13
Limit to events on or before the specified end time.
updatedafter
ISO8601 Date/Time, e.g. 2014-09-22T04:13:13
Limit to events updated after the specified time.

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.
min values must be less than max values.
rectangles may cross the date line by using a minlongitude<-180 or maxlongitude>180.

minlatitude
Decimal degrees: [-90,90]
Limit to events with a latitude larger than the specified minimum.
maxlatitude
Decimal degrees: [-90,90]
Limit to events with a latitude smaller than the specified maximum.
minlongitude
Decimal degrees: [-360,360]
Limit to events with a longitude larger than the specified minimum.
maxlongitude
Decimal degrees: [-360,360]
Limit to events with a longitude smaller than the specified maximum.

Circle

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

latitude
Decimal degrees: [-90,90]
Specify the latitude to be used for a radius search.
longitude
Decimal degrees: [-180,180]
Specify the longitude to be used for a radius search.
minradius
Decimal degrees: [0,180]. Default 0.
Limit to events further than the specified minimum number of degrees from the geographic point defined by the latitude and longitude parameters. This option is mutually exclusive with minradiuskm and specifying both will result in an error.
minradiuskm
Kilometers: [0, 6371]
Limit to events further than the specified minimum number of kilometers from the geographic point defined by the latitude and longitude parameters. This option is mutually exclusive with minradius and specifying both will result in an error.
maxradius
Decimal degrees: [0,180]
Limit to events within the specified maximum number of degrees from the geographic point defined by the latitude and longitude parameters. This option is mutually exclusive with maxradiuskm and specifying both will result in an error.
maxradiuskm
Kilometers: [0, 6371]
Limit to events within the specified maximum number of kilometers from the geographic point defined by the latitude and longitude parameters. This option is mutually exclusive with maxradius and specifying both will result in an error.

Other

mindepth
Decimal kilometers: [-100, 1000]
Limit to events with depth more than the specified minimum.
maxdepth
Decimal kilometers: [-100, 1000]
Limit to events with depth less than the specified maximum.
minmagnitude
Decimal.
Limit to events with a magnitude larger than the specified minimum.
maxmagnitude
Decimal.
Limit to events with a magnitude smaller than the specified maximum.
includeallorigins
Boolean "true"/"false". Default 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
includeallmagnitudes
Boolean "true"/"false". Default 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 interchangable with includeallmagnitudes
includearrivals
Boolean "true"/"false". Default false.
Specify if phase arrivals should be included.
NOTE: NOT CURRENTLY IMPLEMENTED
includedelete
Boolean “true”/“false”. Default false.
Specify if deleted products should be incuded.
NOTE: Only works when specifying eventid parameter.
eventid
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.
limit
Integer: [1,20000]. Default unlimited.
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".
offset
Integer: [1,∞]
Return results starting at the event count specified, starting at 1.
orderby
Order the result.
time
(Default) order by origin descending time
time-asc
order by origin ascending time
magnitude
order by descending magnitude
magnitude-asc
order by ascending magnitude
catalog
Use the Catalogs Method to find available catalogs.
Limit to events from a specified catalog.
NOTE: when catalog and contributor are omitted, the most preferred information from any catalog or contributor for the event is returned.
contributor
Use the Contributors Method to find available contributors.
Limit to events contributed by a specified contributor.
NOTE: when catalog and contributor are omitted, the most preferred information from any catalog or contributor for the event is returned.

Extensions

format
Specify the output format
quakeml
(Default) Response format is Quakeml 1.2. Mime-type is "application/xml".
csv
Response format is CSV. Mime-type is "text/csv".
NOTE: only summary event information is available in this format.
geojson
Response format is GeoJSON. Mime-type is "application/json".
callback
Convert GeoJSON output to a JSONP response using this callback. Mime-type is "text/javascript".
jsonerror
Request JSON(P) formatted output even on API error results. Accepts “true” or “false”. Default: “false”
kml
Response format is KML. Mime-type is "vnd.google-earth.kml+xml".
kmlcolorby
How earthquakes are colored. "age" (default), or "depth".
kmlanimated
Whether to include timestamp in generated kml, for google earth animation support. "false" (default), or "true".
xml
This format is only available for the count method. Response format is xml. Mime-type is "application/xml".
text
This format is only available for the count and version methods. Response format is plain text. Mime-type is "text/plain".
eventtype
Limit to events of a specific type. "earthquake" will filter non-earthquake events.
reviewstatus
Limit to events with a specific review status, default all.
automatic
Limit to events with review status "automatic".
reviewed
Limit to events with review status "reviewed".
minmmi
Decimal: [0,12]
Minimum value for Maximum Modified Mercalli Intensity reported by ShakeMap.
maxmmi
Decimal: [0,12]
Maximum value for Maximum Modified Mercalli Intensity reported by ShakeMap.
mincdi
Decimal: [0,12]
Minimum value for Maximum Community Determined Intensity reported by DYFI.
maxcdi
Decimal: [0,12]
Maximum value for Maximum Community Determined Intensity reported by DYFI.
minfelt
Positive Integer
Limit to events with this many DYFI responses.
alertlevel
Limit to events with a specific PAGER alert level, default all.
green
Limit to events with PAGER alert level "green".
yellow
Limit to events with PAGER alert level "yellow".
orange
Limit to events with PAGER alert level "orange".
red
Limit to events with PAGER alert level "red".
mingap
Decimal degrees [0,360]
Limit to events with no less than this azimuthal gap.
maxgap
Decimal degrees [0,360]
Limit to events with no more than this azimuthal gap.
minsig
Positive integer.
Limit to events with no less than this significance.
maxsig
Positive integer.
Limit to events with no more than this significance.
producttype
Examples: "moment-tensor", "focal-mechanism", "shakemap", "losspager", "dyfi".
Limit to events that have this type of product associated.