Description
The fdsnws-event web service returns event (earthquake) information from catalogs originating from the NEIC and the ISC data centers. (Please read the DISCLAIMER statement below.)
Events may be selected based on location, time, catalog, contributor and internal identifiers. By default, events are retrieved from the NEIC PDE catalog for recent events and then the ISC catalog when it becomes available. These default results include only that catalog’s “primary origin” and “primary magnitude” for each event, they may optionally include all available magnitude estimates.
By default results are returned as XML in QuakeML format (schema), but may also be requested in text formats.
This service is an implementation of the FDSN web service specification version 1.
DISCLAIMER:
The IRIS offering of the fdsnws-event service is provided as a convenience to our users and serves as an internal catalog for some of our tools. As it is a collection of first-run bulletins from the NEIC and ISC, the results returned should be considered NON AUTHORITATIVE and NOT CURRENT for the purposes of seismic study. For this reason, we encourage users to make refined searches to the NEIC and ISC URLs provided below to get the most current, authoritative origin records on earthquakes of interest.
International Seismological Centre (ISC):
http://isc-mirror.iris.washington.edu/fdsnws/event/1/
http://www.isc.ac.uk/fdsnws/event/1/
United States Geological Survey (NEIC):
http://earthquake.usgs.gov/fdsnws/event/1/
Nomenclature primer: An earthquake is referred to as an event. Events are published by different entities in compilations known as catalogs. The same event may appear in multiple catalogs. There are often multiple estimates of an earthquake’s time and location; each is known as an origin or an origin estimate. Each of these origins may have one or more estimates of an earthquake’s size, known as magnitude or magnitude estimate.
Web service clients that use this service can be found on the Client list. In particular the command-line FetchEvent script will request information from this service, parse the returned XML and print or save simple ASCII information.
Event catalogs and citation
The IRIS DMC receives earthquake location and magnitude information from the following sources (catalogs , contributors):
- USGS NEIC: PDE catalog & near real-time ENS messages. (citation information)
- ISC (citation information)
- Global CMT project (citation information)
By default, events are retrieved from the NEIC PDE catalog for recent events and then the ISC catalog when it becomes available. Any catalog may be specified via the catalog=
parameter. Use +
for a space character, so that NEIC PDE is queried using catalog="NEIC PDE"
. For a complete list of IRIS held event catalogs, click the catalogs link at the start of this section.
The same event may be published in multiple catalogs.
Event selection
The service allows events to be selected by the following criteria (see the service interface for detailed usage):
- geographic region, rectangular area or radius from a point
- time range
- depth and magnitude
- catalog and contributor
- events updated after a specific date
Formats
QuakeML
The QuakeML format is an XML schema originally created at ETH Zurich and collaboratively developed with international partners. For further information see https://quake.ethz.ch/quakeml/. As specified in the FDSN web service specification this service returns in the QuakeML 1.2 schema.
Text
The text format contains key event parameters separated by vertical bar characters (|). An example:
EventID|Time|Latitude|Longitude|Depth|Author|Catalog|Contributor|ContributorID|MagType|Magnitude|MagAuthor|EventLocationName 3380339|2012-09-12T11:27:51|-10.1105|161.0712|87.3|NEIC|NEIC PDE|NEIC ALERT|c000clxn|MB|5.2|NEIC|SOLOMON ISLANDS 3380338|2012-09-12T09:37:29|24.99|123.192|15.4|NEIC|NEIC PDE|NEIC PDE-Q||MB|4.8|NEIC|SOUTHWESTERN RYUKYU ISLANDS 3380337|2012-09-12T09:20:54|-32.485|-68.523|101.8|NEIC|NEIC PDE|NEIC PDE-Q||MB|4.7|NEIC|MENDOZA PROVINCE, ARGENTINA
The text format is not available for requests that are to include all magnitudes.
Origins
Preferred origins are determined by each catalog’s contributor.
By default, only the selected catalog’s preferred origin will be returned. These origins have been designated as preferred by the catalog’s contributor.
Note: The NEIC ALERT origins are removed from the DMC event system when estimates for the official PDE catalog become available. Likewise, as origin estimates for the PDE are updated they are replaced in the DMC system as needed.
1 Only origins relating to the selected catalog will be returned.
Magnitudes
Magnitudes are automatically ranked to determine the preferred (Primary) magnitudes
An event may have multiple magnitudes associated with it. These magnitudes are automatically ranked2 by the DMC using the following precedence (in order):
Magnitude author: GCMT, UCMT, WCMT, NEIC, NEIS, ISC, any magnitude contributed by the NEIC
Followed by magnitude type : MW, MB, MS, ML, MD
When only a single magnitude per event is required, then the highest-ranked magnitude from the selected catalog is used. This is known as the “preferred” or “primary” magnitude. For example, if a GCMT-authored MW magnitude is present in the requested catalog, then it will be designated primary over all others.
Magnitude estimates greater than 5.0 from authors or contributors not in the list above will never be designated as primary (the values will remain available).
2 Important: The designation of a primary (a.k.a. preferred) magnitude is provided as a convenience, but has not been reviewed by a human. For official earthquake magnitude estimates please consult the National Earthquake Information Center or other national or regional authorities.
Behavior of magtype, minmag, maxmag, and includeallmagnitudes
- criteria (if any) are applied to the magnitude(s) specified by
magtype
. - if NO criteria (minmag or maxmag) are specified, then…
- if a specific magtype is specified, an event MUST have at least ONE magnitude reported with that type
- This comparison is case-insensitive. so
magtype=mw
will match mw, Mw, MW, etc.
- This comparison is case-insensitive. so
- if magtype is all or preferred, then no filtering is done.
- if a specific magtype is specified, an event MUST have at least ONE magnitude reported with that type
- only events matching above criteria are selected.
includeallmagnitudes=TRUE
means retrieve ALL magnitudes for the selected events.includeallmagnitudes=FALSE
will either:- If
magtype=M
, then show selected events along with the highest-ranked magnitude of type M (which may NOT be one that passed the criteria) - Otherwise, show only the preferred magnitude for the selected events
- If
To get All magnitudes of a specific type, use includeallmagnitudes=TRUE and then post-process (filter) the results.
Here is a chart describing how the magtype, minmag, maxmag, and includeallmagnitudes parameters are applied.
magtype | includeallmagnitudes | Events filtered by… | returns… | sample | |
---|---|---|---|---|---|
A3 | preferred | FALSE | Preferred mags | Preferred mag | link |
B | preferred | TRUE | Preferred mags | All mags | link |
C | M | FALSE | All mags of type M | best mag of type M4 | MW MB MS |
D | M | TRUE | All mags of type M | All mags | MW MB MS |
E | all | FALSE | All mags | Preferred mag | link |
F | all | TRUE | All mags | All mags | link |
3 This default case is the same as if magtype and includeallmagnitudes were not included in the URL.
4 The highest-ranking magnitude of the specified magnitude type is returned. If an event has multiple magnitudes of the same type, then the returned value may not be the one that matched the magnitude limits.
Contributor Search
Using contributor=
will confine results to events that contain origins provided by that contributor. Additionally, the results will be modified as described in this table:
Additional Parameters | Information returned |
---|---|
none | Preferred origin (by that contributor), preferred magnitude (regardless of contributor) |
includeallmagnitudes | All magnitudes (regardless of contributor or origin) |
Geographic search
Using latitude / longitude boundaries (Bounding Rectangle)
The following four parameters work together to specify a boundary rectangle. All four parameters are optional, but may not be mixed with the parameters used for searching within a defined radius. Values are specified in ± decimal degrees, with the bounding box capable of crossing the ±180° meridian.
Example
.../query?minlatitude=45&maxlatitude=60&minlongitude=-150&maxlongitude=-148
Using a radial boundary (Bounding Radius)
The following four parameters work together to specify a boundary as a great circle radius around a coordinate. latitude
, longitude
, maxradius
and minradius
. All values are specified using decimal degrees.
Examples
.../query?latitude=40.0&longitude=-100.0&maxradius=2
.../query?latitude=40.0&longitude=-100.0&minradius=18.0&maxradius=20
Problems with this service?
Please send an email report of which service you were using, your URL query, and any error feedback to:
data-help AT earthscope.org
We will address your issue as soon as possible.