Web services: Bulletin search

Output event parametric data in either QuakeML or ISF from the ISC Bulletin. Events may be selected by region, time, magnitude, depth, and number of defining phases. Returned data comprise of:

  • prime (preferred) hypocentre origins;
  • secondary estimates of hypocentres (optional);
  • magnitudes (optional);
  • phase/arrival data - travel-times, amplitudes, etc. (optional);
  • focal mechanism solutions (optional);

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











Bulletin search: 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>][<defining-phases-limits>][<output-options>]

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.

Parameters in square brackets ([...]) are optional.

Example query 1:

Output prime hypocentres from events in the Reviewed ISC Bulletin between 2009-02-22 15:00:00 and 2009-04-22 15:00:00 where the magnitude >= 5.5:

QuakeML format:

http://www.isc.ac.uk/cgi-bin/web-db-run?out_format=QuakeML&request=REVIEWED&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=Any&prime_only=on

ISF format:

http://www.isc.ac.uk/cgi-bin/web-db-run?out_format=ISF&request=REVIEWED&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=Any&prime_only=on

Example query 2:

Output all hypocentres (prime and secondary estimates), phase data, and magnitudes from events in the ISC Bulletin between 2009-02-22 15:00:00 and 2009-04-22 15:00:00 where the magnitude > 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=COMPREHENSIVE&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=Any&include_magnitudes=on&include_phases=on

ISF format:

http://www.isc.ac.uk/cgi-bin/web-db-run?out_format=ISF&request=COMPREHENSIVE&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=Any&include_magnitudes=on&include_phases=on

Description of query options:

<output-format>
Parameter name Possible values Description
out_format= <QuakeML>|<ISF>
  • QuakeML - XML stream. Strongly recommended for use in web services;
  • ISF: IASPEI Seismic Format - a fixed format bulletin;


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


<defining-phases-limits> (Optional)
Search for events by the number of defining phases used in computing the prime hypocentre.
Note: for events without an ISC hypocentre, the number of defining phases is generally unknown.
Parameter name Possible values Description
min_def= any integer Minimum number of defining phases
max_def= any integer Maximum number of defining phases.
null_phs= [<on>] If set to 'on', events with no known number of defining phases will still be output if a min_def or max_def is specified.


<output-options> (Optional)
Limits the output of the data to speed up queries. The parameters can either be set to 'on' or left empty.
Parameter name Possible values Description
prime_only= [<on>] Limits the output of hypocentres for each event to only the prime (preferred) hypocentre. If not set, all hypocentre estimates are output.
include_magnitudes= [<on>] Outputs all magnitude data unless prime_only=on, in which case only the magnitudes associated to the prime hypocentre will be output.
include_phases= [<on>] Outputs all phase data. This includes any picks, travel-time residuals or amplitude data. This will dramatically increase the size of the output.
include_comments= [<on>] Determines whether to include comments in the output. Note: This is most significant if out_format=ISF, where data such as focal mechanism solutions are stored. For QuakeML, this option is less significant.
include_headers= [<on>] Determines whether to include headers in the output. Note: This only applies if out_format=ISF, where a header line will be present for each event.