Help: event v.1

Description

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.

¹ 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 ranked² 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).

² 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.
  • if magtype is all or preferred, then no filtering is done.
• 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

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.

³ This default case is the same as if magtype and includeallmagnitudes were not included in the URL.

⁴ 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:

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?