IRIS DMC FDSNWS event Web Service Documentation

Description

The fdsnws-event web service returns event (earthquake) information from the catalogs submitted to the IRIS DMC.

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 origin and 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.

Below is a full list of service parameters and their usage.

Query Usage

/query?	[geographic-constraints] [depth-constraints] [temporal-constraints] [magnitude-constraints]
	[organization-constraints] [misc-parameters] [format-option] [nodata=404]

or

/query?	(id-options) [includeallmagnitudes] [includeallorigins] [includearrivals] [nodata=404]

where

geographic-constraints	  ::  [boundaries-rect] OR [boundaries-radial]
boundaries-rect		  ::  [minlatitude=<degrees>] [maxlatitude=<degrees>]
				  [minlongitude=<degrees>] [maxlongitude=<degrees>]
boundaries-radial	  ::  [latitude=<degrees>] [longitude=<degrees>] [maxradius=<degrees>] [minradius=<degrees>]
depth-constraints	  ::  [mindepth=<km>] [maxdepth=<km>]
temporal-constraints	  ::  [starttime=<datetime>] [endtime=<datetime>]
magnitude-constraints	  ::  [minmagnitude=<float>] [maxmagnitude=<float>] [magnitudetype=<<all|preferred>|<text>>]
organization-constraints  ::  [catalog=<text>] [contributor=<text>
misc-parameters		  ::  [limit=<integer>] [offset=<integer>] [orderby=<time|magnitude>]
				  [updatedafter=<datetime>] [includeallmagnitude=<true|false>]
				  [includearrivals=<true|false>] [includeallorigins=<true|false>]
format-option		  ::  [format=<xml|text>]
id-options		  ::  (eventid=<id_value>)

(..) required parameter
[..] optional parameter

All parameters must be separated by ampersands (&) as demonstrated in the samples below.

Sample Queries

Detailed Descriptions of each Query Parameter

parameter examples discussion default type
FDSN options
start[time] 2012-11-29 Limit to events occurring on or after the specified start time. any day/time
end[time] 2012-12-01 Limit to events occurring on or before the specified end time. any day/time
BOX search terms incompatible with radial search
minlat[itude] 46.8 Southern boundary. -90° degrees
maxlat[itude] 46.9 Northern boundary. 90° degrees
minlon[gitude] -122 Western boundary. -180° degrees
maxlon[gitude] -121.5 Eastern boundary. 180° degrees
RADIAL search terms incompatible with the box search
lat[itude] 40.0 Specify the central latitude point. 0.0 degrees
lon[gitude] 100.0 Specify the central longitude point. 0.0 degrees
maxradius 5.0 Specify maximum distance from the geographic point defined by latitude and longitude. 180.0 degrees
minradius 1.0 Specify minimum distance from the geographic point defined by latitude and longitude. 0.0 degrees
mindepth -1 Limit to events with depths equal to or greater than the specified depth any float1 (km)
maxdepth 20 Limit to events with depths less than or equal to the specified depth any float1 (km)
minmag[nitude] -1.0 Limit to events with a magnitude larger than or equal to the specified minimum. any float
maxmag[nitude] 8.3 Limit to events with a magnitude smaller than or equal to the specified maximum. any float
magnitudetype
magtype
M Type of Magnitude used to test minimum and maximum limits. Case insensitive. ex. ML Ms mb Mw all preferred preferred text
catalog ISC Specify the catalog from which origins and magnitudes will be retrieved (available catalogs) NEIC PDE or ISC text
contributor NEIC PDE-Q Limit to events contributed by a specified contributor (available contributors). any2 text
limit 25 Limit the results to the specified number of events unlimited integer
offset 20 Return results starting at the event count specified. 1 integer
orderby time–asc Order results by time/ time-asc or magnitude/ magnitude-asc time text3
updatedafter 2000-05-23 Limit to events updated after the specified time (useful for synchronizing events). any day/time
includeallorigins TRUE Retrieve all origins or only the primary origin associated with each event. read more , note false true/false
includeallmagnitudes TRUE Retrieve all magnitudes for the event, or only the primary magnitude. note false true/false
includearrivals TRUE Specify if phase arrivals should be included. note details false true/false
eventid 1234 Retrieve an event based on the unique ID numbers assigned by the IRIS DMC4 text
format text Specify format. Valid formats include xml and text xml text5
nodata 404 Specify which HTML Status code is returned when no data is found.6 204 204 or 404

1 Values increase positively with depth.

2 When requesting a contributor, the result includes a primary origin as specified by the contributor

3 Valid orderby values include:
time — order by origin descending time [default]
time-asc — order by origin ascending time
magnitude — order by descending magnitude
magnitude-asc — order by ascending magnitude

4 When eventid is used, then only the includeallmagnitudes, includeallorigins, and includearrivals parameters are also allowed

5 For format=text , only the primary origin and magnitude for each event will be returned.

6 By default, the service returns a HTTP response code 204, which means the request was successful, but no data (no content) was retrieved. However, because there was no “error”, no error message is generated and it may appear that the browser did nothing. To force an empty query response to display an error message, add nodata=404 to the URL.

Magnitudes

Results are filtered by applying the minmag and maxmag constraints to either the highest automatically ranked magnitude (a.k.a. “preferred” magnitude) or to magnitudes specified by magtype. Use includeallmagnitudes to then specify whether one or multiple magnitudes are included in the results.

Some common types (there are many) include:
Ml — local (Richter) magnitude
Ms — surface magnitude
mb — body wave magnitude
Mw — moment magnitude

Alternatively, special magtypes may be specified:
all — compare minmag and maxmag to all magnitudes in a catalog
preferred — compare minmag and maxmag to the highest-ranked magnitude for each event in a catalog. (this is the same as not specifying a magtype)

magtype comparisons are case-insensitive to accommodate historical catalogs where case was not preserved.

Format

Output may be formatted as text or XML. If format=xml or format is not specified, then the results will be returned in quakeml format. When format=text, then a simple | separated table is returned. Note, format=text is not available for includeallorigins=true, includeallmagnitudes=true, or includearrivals=true. read more


WADL

Retrieve the WADL associated with this service:

application.wadl


Time Formats

Year, Month, Day in Month — Time:

YYYY-MM-DDThh:mm:ss[.ssssss] ex. 1997-01-31T12:04:32.123

YYYY-MM-DD ex. 1997-01-31 a time of 00:00:00 is assumed

Where:

YYYY	:: four-digit year
MM	:: two-digit month (01=January, etc.)
DD	:: two-digit day of month (01 through 31)
T	:: date-time separator
hh	:: two digits of hour (00 through 23) (AM/PM NOT allowed)
mm	:: two digits of minute (00 through 59)
ss	:: two digits of second (00 through 59)
ssssss	:: one to six digits representing decimal fractions of a second, down to microseconds

1.1.0
wslive5.iris.washington.edu

FDSNWS event web service