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/
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] [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>] [includeallmagnitudes=<true|false>] format-option :: [format=<xml|text|geocsv>] id-options :: (eventid=<id_value>)
(..) required parameter
[..] optional parameter
All parameters must be separated by ampersands (&) as demonstrated in the samples below.
Sample Queries
- http://service.iris.edu/fdsnws/event/1/query?eventid=609301
- /fdsnws/event/1/query?minmagnitude=8.5
- /fdsnws/event/1/query?starttime=2011-01-08T00:00:00&endtime=2011-01-09T00:00:00&catalog=NEIC%20PDE
- /fdsnws/event/1/query?starttime=2011-01-07T14:00:00&endtime=2011-02-07&minlatitude=15&maxlatitude=40&minlongitude=-170&maxlongitude=170&minmagnitude=5&includeallmagnitudes=true&orderby=magnitude
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. | 0 | 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 |
| includeallmagnitudes | TRUE | Retrieve all magnitudes for the event, or only the primary magnitude. note | 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, text, and geocsv |
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 timemagnitude — order by descending magnitudemagnitude-asc — order by ascending magnitude
4 When eventid is used, then only the includeallmagnitudes parameter is 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) magnitudeMs — surface magnitudemb — body wave magnitudeMw — moment magnitude
Alternatively, special magtypes may be specified:all — compare minmag and maxmag to all magnitudes in a catalogpreferred — 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 includeallmagnitudes=true. read more Additionally, if format=geocsv is specified, the results will be returned in GeoCSV text format delimited with a simple | character.
WADL
Retrieve the WADL associated with this service:
Date and 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
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.
