Description
The ph5ws-event web service returns event (shot) information for controlled source PH5 experiments stored at the IRIS DMC.
Events may be selected based on catalog, time, location, and internal identifiers.
By default results are returned as XML in QuakeML format (schema), but may also be requested in a pipe-delimited text format.
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? (catalog=<catalog-id>) [geographic-constraints] [temporal-constraints] [format-option] [id-options] [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>] temporal-constraints :: [starttime=<date>] [endtime=<date>] format-option :: [format=<xml|shottext>] id-options :: [shotline=<id_value>] [shotid=<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/ph5ws/event/1/query?catalog=8A
- http://service.iris.edu/ph5ws/event/1/query?catalog=8A&shotline=001&shotid=5013
Alternatively, catalogs may be identified using PH5 report numbers. - http://service.iris.edu/ph5ws/event/1/query?catalog=15-016
- http://service.iris.edu/ph5ws/event/1/query?catalog=15-016&shotline=001&shotid=5013
Detailed Descriptions of each Query Parameter
parameter | examples | discussion | default | type |
---|---|---|---|---|
catalog | ZI or 15-016 |
The catalog of events. Catalogs are identified by PH5 FDSN Network codes and/or PH5 Report Numbers. Accepts wildcards and lists. | text | |
shotline | 001 | The 3-character shot line number that shots belong to. Accepts wildcards and lists. | any | text |
shot[id] | 5013 | The shot (event) id1. Accepts wildcards and lists. | any | text |
FDSN options | ||||
start[time] | 2015-06-29 | Limit to events occurring on or after the specified start time. | any | day/time |
end[time] | 2015-07-01 | Limit to events occurring on or before the specified end time. | any | day/time |
BOX search terms incompatible with radial search | ||||
minlat[itude] | 34.00 | Southern boundary. | -90° | degrees |
maxlat[itude] | 38.00 | Northern boundary. | 90° | degrees |
minlon[gitude] | -78.00 | Western boundary. | -180° | degrees |
maxlon[gitude] | -73.00 | Eastern boundary. | 180° | degrees |
RADIAL search terms incompatible with the box search | ||||
lat[itude] | 36.00 | Specify the central latitude point. | 0.0 | degrees |
lon[gitude] | -79.00 | 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 | 0.5 | Specify minimum distance from the geographic point defined by latitude and longitude . |
0.0 | degrees |
format | shottext | Specify format. Valid formats include xml , shottext and geocsv |
xml | text |
nodata | 404 | Specify which HTML Status code is returned when no data is found.2 | 204 | 204 or 404 |
1 Note that shotid
are not necessarily unique. To select a particular shot, the shotline
parameter must also be assigned.
2 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.
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=shottext
or format=geocsv
, then a simple |
separated table is returned.
Geographic search
Using latitude / longitude boundaries (Bounding Rectangle)
The following four parameters work together to specify a boundary rectangle. All four parameters are optional, but may not be mixed with the parameters used for searching within a defined radius. Values are specified in decimal degrees, with the bounding box capable of crossing the ±180° meridian.
Example
.../query?minlatitude=35&maxlatitude=36&minlongitude=-79&maxlongitude=-78
Using a radial boundary (Bounding Radius)
The following four parameters work together to specify a boundary as a great circle radius around a coordinate. latitude
, longitude
, maxradius
and minradius
. All values are specified using decimal degrees.
Examples
.../query?latitude=36.0&longitude=-79.0&maxradius=2
.../query?latitude=36.0&longitude=-79.0&minradius=0.5&maxradius=2
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
Requests that return no result
By default, this web service return an HTTP code of 404 (rather than 204) when a request is “successful”, but there were no matching results. If 204 is chosen and no results are found, a web browser will not refresh its previous results. When 404 is used, a browser will update any headers (or tags) displayed on the screen, but will list no values. To force the service to return a 204, add the query parameter &nodata=204
.
Wildcards and Lists
Wildcards
The question mark ?
represents any single character (exactly one), while the asterisk *
represents zero or more characters.
Lists
Multiple items may also be retrieved using a comma separated list. Wildcards may be included in the list. For example, with channel codes: channel=EH?,BHZ,BHE
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@earthscope.org
We will address your issue as soon as possible.