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.gxjydl.com/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.gxjydl.com/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.gxjydl.com/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.gxjydl.com/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.gxjydl.com/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 2025 |
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 2025 |
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.
|
