ISC FDSNWS event Web Service Documentation

Service Interface URL Builder Help Revisions

Description

The fdsnws-event web service returns seismic event¹ information from the ISC Bulletin². Details of how the ISC Bulletin is produced can be read in the Bulletin Summary or in brief on the ISC website.

Events may be selected based on location, time, contributor, magnitude and event id (an ISC internal identifier). By default results include only the event's prime origin and the magnitudes associated to the the prime origin. They may optionally include all available origin and magnitude estimates.

By default results are returned as XML in QuakeML format schema, but may also be requested in ISF format.

This service is an implementation of the FDSN web service specification version 1.

Please remember that data obtained from our fdsn-event webservice should always be appropriately cited. More information about proper catalogue citations can be found on the citations page under Data retrieved from the ISC web site.

Nomenclature:

Agency/ISC data contributor
- An academic or government institute, seismological organisation or company, geological/meteorological survey, station operator or author that reports or contributed data in the past to the ISC or one of its predecessors. Agencies may contribute data to the ISC directly, or indirectly through other ISC data contributors.
Agency code
- A unique, maximum eight-character code for a data reporting agency (e.g.~NEIC, GFZ, BUD) or author (e.g.~ISC, EHB, IASPEI). Often the agency code is the commonly used acronym of the reporting institute.
Bulletin
- An ordered list of event hypocentres, uncertainties, focal mechanisms, network magnitudes, as well as phase arrival and amplitude observations associated to each event. An event bulletin may list all the reported hypocentres for an event. The convention in the ISC Bulletin is that the preferred (prime) hypocentre appears last in the list of reported hypocentres for an event.
Catalogue
- An ordered list of event hypocentres, uncertainties and magnitudes. An event catalogue typically lists only the preferred (prime) hypocentres and network magnitudes.
Event¹
- A natural (e.g.~earthquake, landslide, asteroid impact) or anthropogenic (e.g.~explosion) phenomenon that generates seismic waves and its source can be identified by an event location algorithm.
Hypocentre/Origin
- An estimate of the event's location (latitude, longitude and depth) and time.
ISC Bulletin²
- The comprehensive bulletin of the seismicity of the Earth stored in the ISC database and accessible through the ISC website. The bulletin contains both natural and anthropogenic events. Currently the ISC Bulletin spans more than 50 years (1960-to date) and it is constantly extended by adding both recent and past data. Eventually the ISC Bulletin will contain all instrumentally recorded events since 1900.
Network magnitude
- The event magnitude reported by an agency or computed by the ISC locator. An agency can report several network magnitudes for the same event and also several values for the same magnitude type. The network magnitude obtained with the ISC locator is defined as the median of station magnitudes of the same magnitude type.
Prime hypocentre
- The preferred hypocentre solution for an event from a list of hypocentres reported by various agencies or calculated by the ISC. If there is an ISC origin for the event it will be prime

Restrictions

In release 1.1.0 returned data is restricted to 40,000 events and one query per IP address can run. These restrictions will be subject to review based on usage of the service.

Event catalogues and citation

The ISC receives earthquake location and magnitude information calculated by many contributors (contributors) and additional data (e.g. arrivals and moment tensors ) from many others. The complete list of data contributors can be viewed here: contributing agencies

By default and currently the only option, events are retrieved from the ISC Bulletin.

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
contributors

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.

ISF

ISF is the IASPEI approved standard format for the exchange of parametric seismological data (hypocentres, magnitudes, phase arrivals, moment tensors, etc.). It was adopted as standard in August 2001 by IASPEI's Commission on Seismic Observation and Interpretation at the Scientific Assembly in Hanoi, Vietnam. The format is an extenstion of IMS1.0.

The full documentation of the different versions is available to download:

The example below shows one event and the many different origins, magnitudes and their variation in type and value. It also indicates the event number for an eventid request

http://www.gxjydl.com/fdsnws/event/1/query?eventid=600800693

Event  600800693 Turkey
   Date       Time        Err   RMS Latitude Longitude  Smaj  Smin  Az Depth   Err Ndef Nsta Gap  mdist  Mdist Qual   Author      OrigID
2012/03/20 00:39:22.98   0.72 0.690  37.8055   29.1657  14.0  11.8   3   0.0f        27       85   3.99  75.90     uk IDC       00874574
2012/03/20 00:39:24.10   1.67        37.7550   29.2140   9.8   6.0  69  13.0         33                               MOS       02528566
2012/03/20 00:39:24.25        0.530  37.8437   29.1477                  21.8                  26                   ke DDA       02381601
2012/03/20 00:39:24.54   0.42 1.151  37.8644   29.1763 2.872 2.442 139   6.4  3.49  279  256  18   0.16  75.83 m i ke ISCJB     04598458
2012/03/20 00:39:24.80        0.220  37.8275   29.1233                   5.9         42   41  46   0.10   2.77     ke ISK       00906859
2012/03/20 00:39:24.90   0.09 0.990  37.8358   29.1618   2.7   2.4 134   2.0        130  113  20   0.13  69.55     ke CSEM      03431516
2012/03/20 00:39:26.00        0.480  37.8960   29.1605   3.1   0.8  72   0.1   1.3   27   22 205   1.77            ke THE       03494766
2012/03/20 00:39:26.10   0.68 1.315  37.8205   29.1642 2.971 2.578 134  12.1  4.61  283  256  19   0.12  75.86 m i ke ISC       04248161
 (#PRIME)

Magnitude  Err Nsta Author      OrigID
mb     3.8 0.1   15 IDC       00874574
mb1    3.9 0.1   24 IDC       00874574
mb1mx  3.7 0.1   72 IDC       00874574
mbtmp  3.8 0.1   24 IDC       00874574
ML     3.2 0.1    8 IDC       00874574
MS     2.6 0.2    1 IDC       00874574
Ms1    2.6 0.2    1 IDC       00874574
ms1mx  2.4 0.1   66 IDC       00874574
mb     4.1       11 MOS       02528566
Ml     3.9          DDA       02381601
mb     3.7       20 ISCJB     04598458
ML     3.7       29 ISK       00906859
mb     4.0 0.2   11 CSEM      03431516
ML     3.7 0.1    5 THE       03494766
mb     3.8 0.1   20 ISC       04248161

Origins

Prime origins

By default, only the selected prime origin will be returned and only the prime origin and its magnitudes will be used for the event search. To include secondary origins as part of the search, specify includeallorigins=true.

Magnitudes

It is important to note that the ISC Bulletin has no preferred event magnitude and therefore magnitude criteria will be applied to the magnitudes of the prime hypocentre only, unless includeallmagnitudes or includeallorigins is set true.

If the prime hypocentre has no magnitudes then the event cannot be returned if magnitude criteria are used, unless includeallmagnitudes/includeallorigins are set true. If an event has no magnitudes then it will not be returned if magnitude criteria are set.

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 then no filtering is done.
only events matching above criteria are selected.
includeallmagnitudes=TRUE means retrieve ALL magnitudes for the selected events.

To get All magnitudes of a specific type, use includeallmagnitudes=TRUE and then post-process (filter) the results.

Contributor Search

Using contributor= will confine results to events that contain origins calulated by that contributor. Additionally, the results will be modified as described in this table:

Additional Parameters	Information returned
none	Prime origin of an event where the prime is by that contributor, magnitudes of the prime origin
includeallorigins	All origins (regardless of contributor) of an event where one origin is from that contributor and all magnitudes.
includeallmagnitudes	All origins (regardless of contributor) and magnitudes of an event where one magnitude is from that contributor.

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