IRIS DMC PH5WS dataselect Web Service Documentation

Description

The ph5ws-dataselect service provides access to PH5 active and passive source seismic data. The service supports requests by FDSN standard parameters and by shot-id. Data may be selected using the FDSN standard network, station, location, channel identifiers and a data format specification (mseed or sac) or by PH5 specialized parameters for request by shot-id.

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 this request by Shot. 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 (starttime=<date>) (endtime=<date>) [format=<mseed|sac>] [std-options]
or 
/query?reqtype=shot (length=<integer>) [shotid=<idnumber>] [shotline=<linenumber>] [arrayid=<arraynumber>]
                    [offset=<seconds>] [format=<mseed|sac>] [std-options]

where

std-options ::
    [net=<network>] [sta=<station>] [loc=<location>] [cha=<channel>] [reportnum=<reportnum>] 
    [decimation=<integer>] [reduction=<float>] [nodata=404]

(..) required
[..] optional

Query parameters are joined by ampersands ”&” without blank space (see the sample queries).

Sample Queries

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 or Shot. 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
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
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
format mseed Determines the return format. Select from “mseed” or “sac”2. mseed string
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 Request:

Parameters examples discussion default type
Options
format sac Determines the return format. Select from “mseed” or “sac”2. mseed string
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
array[id] 001 Specifies the array id for a request by shot. 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) or SAC format.
  • Shot request type supports miniSEED (mseed) or SAC format.

where

  • mseed -> miniSEED
  • sac -> SAC binary

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


WADL

Retrieve the WADL associated with this service:

application.wadl


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, FDSN services return an HTTP code of 204 when a request is “successful”, but there were no matching results. This behavior allows automated systems to know the difference between a successful request (with no data) from an incorrect request (bad parameter names, invalid URL, etc). Since no content is returned, the page on the web browser will not change. To force the service to return a 404, add the query parameter nodata=404.

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

PH5WS dataselect web service