Web services: Event catalogue

Output a catalogue of events in either QuakeML or as a CSV file from the ISC Bulletin. The output is limited to the prime (preferred) hypocentre and the magnitude values for each event, providing a condensed list of events. Events may be selected by region, time, magnitude, and depth. Returned data comprise of:

  • prime (preferred) hypocentre origins;
  • magnitude - all magnitudes or those fitting your selection (specify author, type, and/or value);

An overview of the available web services guides can be found on the web services page.














Event catalogue: URL construction

USAGE:
http://www.isc.ac.uk/cgi-bin/web-db-run?<output-format><database-choice><geographic-region><time-range>[<depth-limits>][<magnitude-limits>]

Each <query-option> is comprised of one or more parameters, which are described in detail below. Each parameter needs to be separated by an ampersand (&) as shown in the examples.

Queries or parameters in square brackets ([...]) are optional.

Example query 1:

Output a catalogue of events (prime hypocentres and magnitudes) in the ISC Bulletin between 2009-02-22 15:00:00 and 2009-04-22 15:00:00 where the magnitude computed by GCMT >= 5.5

QuakeML format:

http://www.isc.ac.uk/cgi-bin/web-db-run?out_format=CATQuakeML&request=COMPREHENSIVE&searchshape=GLOBAL&start_year=2009 &start_month=02&start_day=22&start_time=15:00:00&end_year=2009&end_month=04&end_day=22&end_time=15:00:00 &min_mag=5.5&req_mag_agcy=GCMT&req_mag_type=Any

CSV file:

http://www.isc.ac.uk/cgi-bin/web-db-run?out_format=CATCSV&request=COMPREHENSIVE&searchshape=GLOBAL&start_year=2009 &start_month=02&start_day=22&start_time=15:00:00&end_year=2009&end_month=04&end_day=22&end_time=15:00:00 &min_mag=5.5&req_mag_agcy=GCMT&req_mag_type=Any

Example query 2:

Output a catalogue of events (prime hypocentres and magnitudes), in the Reviewed ISC Bulletin between 2009-02-22 15:00:00 and 2009-04-22 15:00:00 where the body-wave magnitude (mb) associated to the prime hypocentre >= 5.5. Limit events to within 30 degrees of Lat: 25 N; Lon: 36 E

QuakeML format:

http://www.isc.ac.uk/cgi-bin/web-db-run?out_format=QuakeML&request=REVIEWED&searchshape=CIRC&ctr_lat=25&ctr_lon=36&radius=30&max_dist_units=deg &start_year=2009&start_month=02&start_day=22&start_time=15:00:00&end_year=2009&end_month=04&end_day=22 &end_time=15:00:00 &min_mag=5.5&req_mag_agcy=prime&req_mag_type=MB

CSV file:

http://www.isc.ac.uk/cgi-bin/web-db-run?out_format=CATCSV&request=REVIEWED&searchshape=CIRC&ctr_lat=25&ctr_lon=36&radius=30&max_dist_units=deg &start_year=2009&start_month=02&start_day=22&start_time=15:00:00&end_year=2009&end_month=04&end_day=22 &end_time=15:00:00 &min_mag=5.5&req_mag_agcy=prime&req_mag_type=MB

Description of query options:

<output-format>
Parameter name Possible values Description
out_format= <CATQuakeML>|<CATCSV>
  • CATQuakeML (QuakeML) - XML stream. Strongly recommended for use in web services;
  • CATCSV: A CSV formatted file - one line per event;


<database-choice>
Parameter name Possible values Description
request= <COMPREHENSIVE>|<REVIEWED>
  • COMPREHENSIVE: Searches the ISC Bulletin;
  • REVIEWED: Searches the Reviewed ISC Bulletin - a subset of the ISC Bulletin, which is reviewed by ISC analysts.


<geographic-region>
Parameter name Possible values Description
searchshape= <GLOBAL>|<RECT>|<CIRC>|<FE>|<POLY>
  • GLOBAL: Events are not restricted by region;
  • RECT: Rectangular search;
  • CIRC: Circular search;
  • FE: Flinn-Engdahl region search;
  • POLY: Customised polygon search.
Dependent parameters if: searchshape=RECT
bot_lat= -90 to 90 Bottom latitude of rectangular region
top_lat= -90 to 90 Top latitude of rectangular region
left_lon= -180 to 180 Left longitude of rectangular region
right_lon= -180 to 180 Right longitude of rectangular region
Dependent parameters if: searchshape=CIRC
ctr_lat= -90 to 90 Central latitude of circular region
ctr_lon= -180 to 180 Central longitude of rectangular region
max_dist_units= <deg>|<km> Units of distance for a circular search: degrees or kilometres
radius= any float or integer Radius for circular search region
  • 0 to 180 if max_dist_units=deg
  • 0 to 20015 if max_dist_units=km
Dependent parameters if: searchshape=FE
srn= 1 to 50 Seismic region number for a Flinn-Engdahl region search
grn= 1 to 757 Geographic region number for a Flinn-Engdahl region search
Dependent parameters if: searchshape=POLY
coordvals= lat1,lon1,lat2,lon2,lat3,lon3,lat4,lon4,lat1,lon1 Comma seperated list of coordinates for a desired polygon. Latitude needs to be before longitude. Coordinates in the western and southern hemispheres should be negative.


<time-range>
Parameter name Possible values Description
start_year= 1900 to 2024 Starting year for events
start_month= 1 to 12 Starting month for events
start_day= 1 to 31 Starting day for events
start_time= 00:00:00 to 23:59:59 Starting time for events (HH:MM:SS)
end_year= 1900 to 2024 Ending year for events
end_month= 1 to 12 Ending month for events
end_day= 1 to 31 Ending day for events
end_time= 00:00:00 to 23:59:59 Ending time for events (HH:MM:SS)


<depth-limits> (Optional)
Parameter name Possible values Description
min_dep= any float or integer Minimum depth of events (km)
max_dep= any float or integer Maximum depth of events (km)
null_dep= [<on>] If set to 'on', events with no known depth will still be output if a min_dep or max_dep is specified.


<magnitude-limits> (Optional)
Parameter name Possible values Description
min_mag= any float or integer Minimum magnitude of events
max_mag= any float or integer Maximum magnitude of events.
null_mag= [<on>] If set to 'on', events with no known magnitude values will still be output if a min_mag or max_mag is specified.
req_mag_type= <Any>|<MB>|<MS>|<MW>|<ML>|<MD> Limit events to specific magnitude types. Please note: the selected magnitude type will search for all possible magnitudes in that category:
E.g. MB will search for mb, mB, Mb, mb1mx, etc
req_mag_agcy= <Any>|<prime>|<CODE> Limit events to magnitudes computed by the selected agency:
  • Any: magnitudes will not be restricted by author;
  • prime: this will limit magnitudes to those associated with the prime (preferred) hypocentre - this is usually but not always the same author as the prime hypocentre;
  • CODE: restricts events with magnitudes computed by a specific agency (e.g. ISC, NEIC, GCMT, JMA, etc.). See here for a full list of agencies.