Description
The ph5ws-dataselect service provides access to PH5 active and passive source seismic data. The service supports requests by FDSN standard parameters as well as shot and receiver gathers. Data may be selected using the FDSN standard network, station, location, channel identifiers and a data format specification (mseed, sac, segy, or geocsv) or by using additional options only applicable to shot and receiver gather requests.
To support the required fields for the FDSN web service specification version 1 additional parameters have been added to this service. The Standard Options are valid for all request types.
Restrictions:
- The starttime and endtime parameters will be ignored for Shot and Receiver gather requests. Instead use the length parameter.
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?reqtype=fdsn (date-range-options) [channel-options] [misc-options] [format-options] [nodata=404] or /query?reqtype=shot (shot-options) [channel-options] [misc-options] [format-options] [nodata=404] or /query?reqtype=receiver (shot-options) [channel-options] [misc-options] [format-options] [nodata=404]
where
date-range-options :: (start=<time>) (end=<time>) channel-options :: [net=<network>] [sta=<station>] [loc=<location>] [cha=<channel>] [reportnum=<reportnum>] [arrayid=<arraynumber>] shot-options :: (length=<integer>) [shotid=<idnumber>] [shotline=<linenumber>] [offset=<seconds>] receiver-options :: (length=<integer>) [shotid=<idnumber>] [shotline=<linenumber>] [offset=<seconds>] misc-options :: [decimation=<integer>] [reduction=<float>] format-options :: [format=<mseed|sac|segy1|segy2|geocsv>]
(..) required
[..] optional
Query parameters are joined by ampersands ”&” without blank space (see the sample queries).
Sample Queries
- Example of a by SHOT request in SAC format
http://service.iris.edu/ph5ws/dataselect/1/query?reqtype=shot&shotline=001&shotid=5013&array=001&length=60&reportnum=15-016&station=100?&format=sac&nodata=404
- Example of a by SHOT request in SEGY Revision 1 format
http://service.iris.edu/ph5ws/dataselect/1/query?reqtype=shot&shotline=001&shotid=5013&array=001&length=60&reportnum=15-016&station=*&format=segy1&nodata=404
- Example of a RECEIVER gather request in SEG-Y rev. 1 format
http://service.iris.edu/ph5ws/dataselect/1/query?reportnum=10-012&shotid=208?,209?,21??&station=B94&format=segy1&reqtype=receiver&length=30&nodata=404
- Example of a FDSN request. DPZ channels for Community Wavefield Demonstration Experiment (YW) stations 100[1-9]
http://service.iris.edu/ph5ws/dataselect/1/query?reqtype=fdsn&format=mseed&net=YW&sta=100?&cha=DPZ&starttime=2016-06-26T00:00:00&endtime=2016-06-26T05:00:00&nodata=404
- Example of a FDSN request. Vertical channel data for ZI stations 1002&1003 in SAC format
http://service.iris.edu/ph5ws/dataselect/1/query?reqtype=fdsn&format=sac&network=ZI&channel=DPZ&starttime=2015-06-29T04:45:00&endtime=2015-06-29T05:00:00&station=1002,1003&nodata=404
- Example of a FDSN request. Vertical channel data for ZI stations 1002&1003 in MSEED format
http://service.iris.edu/ph5ws/dataselect/1/query?reqtype=fdsn&format=mseed&network=ZI&channel=DPZ&starttime=2015-06-29T04:45:00&endtime=2015-06-29T05:00:00&station=1002,1003&nodata=404
- Example of a FDSN request. YW station 1001 data in GeoCSV in SLIST ZIP format
http://service.iris.edu/ph5ws/dataselect/1/query?format=geocsv.zip.slist&network=YW&starttime=2016-06-21T16:43:58&endtime=2016-06-21T16:43:59&station=1001&nodata=404
- Example of a FDSN request. YW station 1001 data in GeoCSV in TSPAIR INLINE format. Auto scaled by instrument sensitivity.
http://service.iris.edu/ph5ws/dataselect/1/query?format=geocsv.tspair.inline&network=YW&starttime=2016-06-21T16:43:58&endtime=2016-06-21T16:43:59&station=1001&scale=AUTO&nodata=404
Detailed Descriptions of each Query Parameter
FDSN Parameters:
The following parameters are intended to be used with programs that use the FDSN web service specification version 1 query parameters. In addition to the Standard Options, supplementary parameters are also required for each request type “FDSN” and “Shot”.
Commonly Supported Options:
Parameters | examples | discussion | default | type |
---|---|---|---|---|
reqtype | FDSN | The type of data request. Choose from FDSN, SHOT, or RECEIVER. Request type descriptions are in subsequent sections. | FDSN | string |
Standard Options | ||||
net[work] | ZI | Select one or more network codes. Can be SEED network codes or data center defined codes. Accepts wildcards and lists. | any | string |
sta[tion] | 1002 | Select one or more SEED station codes. Accepts wildcards and lists. | any | string |
loc[ation] | — | Select one or more SEED location identifiers. As a special case “—” (two dashes) will be translated to a string of two space characters to match blank location IDs. Accepts wildcards and lists. | any | string |
cha[nnel] | DPZ | Select one or more SEED channel codes. The sample rate is ignored and only the directional component is used (i.e. for the parameter BHZ only the vertical component Z is enforced) Accepts wildcards and lists. | any | string |
report[num] | 15-016 | Select one or more report-num codes. Accepts wildcards and lists. (Synonymous with Network) | any | string |
array[id] | 001 | Specifies the array id for an array of stations. Accepts wildcards and lists. | any | integer |
component | 1 | Select one or more seed directional components (1, 2, 3, … etc.) Accepts wildcards and lists. (Synonymous with Channel). | any | string |
decimation | 2 | Decimate the data by a constant value. Defaults to no decimation. | 0 | float |
reduction | 10 | Reduction velocity in km/sec. | 0 | float |
format | mseed | Determines the return format. Select from “mseed”, “sac”2, “segy1”2, “segy2”2, or “geocsv”3. | mseed | string |
format=geocsv additional options GeoCSV supports an optional tspair (default) or slist text-format and inline (default) or zip content type. These values can be set by appending these arguments in any order with a “.” delimiter to the format=geocsv option.Examples format=geocsv.slist format=geocsv.tspair format=geocsv.zip format=geocsv.inline format=geocsv.inline.slist format=geocsv.zip.tspair ⋮ format=sac additional options SAC supports an additional zip content type (default).Example format=sac.zip |
||||
nodata | 404 | Specify which HTTP status code is returned when no data is found.1 | 204 | 204 or 404 |
FDSN Request:
Parameters | examples | discussion | default | type |
---|---|---|---|---|
Options | ||||
start[time] | 2015-06-29T04:45:00 | Specifies the desired start-time for the requested data. | day/time | |
end[time] | 2015-06-29T05:00:00 | Specifies the desired end-time for the requested data. The entered end-time is internally translated to an equivalent length of time from the start-time. | day/time |
Shot and Receiver Request:
Parameters | examples | discussion | default | type |
---|---|---|---|---|
Options | ||||
length | 60 | Length in seconds of the request data segment | integer | |
shot[id] | 5022 | Specifies the shot (event) id for a request by shot. Accepts wildcards and lists. | any | integer |
shotline | 001 | The 3-character shot line number that holds the shots. Accepts wildcards and lists. | any | integer |
offset | 10 | Time in seconds from shot time to start the trace. | 0 | float |
Output format options:
- FDSN request type supports miniSEED (mseed), SAC, SEGY1 (revision 1), SEGY2 (revision 2), and GeoCSV format.
- Shot request type supports miniSEED (mseed), SAC, SEGY1 (revision 1), SEGY2 (revision 2), and GeoCSV format.
- Receiver request type supports miniSEED (mseed), SAC, SEGY1 (revision 1), SEGY2 (revision 2), and GeoCSV format.
where
- mseed -> miniSEED
- sac -> SAC binary (zip)
- segy1 -> SEGY revision 1 (zip)
- segy2 -> SEGY revision 2 (zip)
- geocsv [.tspair (default) or .slist] [.inline (default) or .zip] -> GeoCSV
1 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.
2 Requests for data in SAC and SEGY format are returned in a compressed ZIP64 file format defined in PKZIP Application Note. Please make sure your ZIP file extraction client supports this format.
3 GeoCSV format supports a single sample SLIST and time-series/sample TSPAIR style text output. Additionally both INLINE and ZIP content types are supported. The text output style and content types can be optionally set by appending these arguments in any order with a “.” delimiter to the format=geocsv option. For example format=geocsv.slist.zip
is equivalent to format=geocsv.zip.slist
.
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
Glob Expressions
Wildcards
The question mark ?
represents any single character (exactly one), while the asterisk *
represents zero or more characters. These wildcards work when specifying a target, but not when specifying a SNCLQ filter.
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
Restricted Data Access
For access to restricted data, requests should be sent to: service/ph5ws/dataselect/1/queryauth
Requests sent to this URL are authenticated via
digest access authentication
in order to establish the caller's credentials. For anonymous access, the user
nobody@iris.edu
and password anonymous
may be used. This
credential has identical data access permission as the regular submit path's:
service/ph5ws/dataselect/1/query
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.