NSF SAGE

NSF SAGE Facility PH5WS dataselect Web Service Documentation

Service interface URL builder Help Revisions

Description

URL Builder

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

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:

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, 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 [email protected] 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:
[email protected]
We will address your issue as soon as possible.

PH5WS dataselect web service