NSF SAGE

NSF SAGE Facility IRISWS rrds Web Service Documentation

Service interface URL builder Help Revisions

Description

URL Builder

The Research Ready Datasets (RRDS) service is a tool for timeseries data selection based on quality control criteria selected by the user. The service returns a request (or more detailed report) designed to be submitted to other web services to retrieve data or metadata.

Below is a full list of service parameters and their usage.

Query Usage

/query? [service-options] [active-options] [passive-options]

where

service-options 	::  [format=<request|report|verbosereport>]
active-options 	 	::  [channel-options] [time-constraints]
  channel-options 	::  [net=<network>] [sta=<station>] [loc=<location>] [cha=<channel>]
  time-constraints 	::  [starttime=<date>] [endtime=<date>]
  metric-constraints* 	::  [<metric_constraint+_lt|_le|_gt|_ge|_eq|_ne>=<value>]
  pass/fail-options 	::  [nomeasurements=<pass|reject>] [pass=<all|any>]
passive-options 	::  [nodata=404]

*Metric constraints are those of the Mustang system and employ a simplified value constraint scheme: See “Metric constraints” below.
Query parameters are joined by ampersands ”&”, without blank space (see the sample queries).

POST Usage

Alternatively, instead of providing parameter-value pairs in the URL, a file containing a selection list can be POSTed to this service. This is the same method used with the fdsnws-station and fdsnws-dataselect webservices. For additional details, including an example selection file, visit the Help section.

nodata=404
percent_availability_eq=100
Network Station Location Channel StartTime EndTime
Network Station Location Channel StartTime EndTime
...

Wildcards are acceptable for Network, Station, Location, and Channel. Click here for time format details.

Sample Queries

LH* channels where the timing_quality metric > 99.99:

LH* channels where the percent_availability metric > 99.0 and the sample_rms metric is <= 2000:

LH* channels where, within frequencies of .003 and .4 Hz, the deviation from the LNM >= 5dB:

Detailed Descriptions of each Query Parameter

parameter examples discussion default type
Service options
format report Specify output format. Accepted values are request, report, and verbosereport, more details. request string
Channel contraints
net[work] IU Select one or more network codes. Can be SEED codes or data center defined codes. Accepts wildcards. any string
sta[tion] ANMO Select one or more SEED station codes. Accepts wildcards. any string
loc[ation] 00 Select one or more SEED location identifier. Use -- for “Blank” location IDs (ID’s containing 2 spaces). Accepts wildcards. any string
cha[nnel] BH1 Select one or more SEED channel codes. Accepts wildcards. any string
Time constraints
start[time] 2015-10-18T00:00:00 Limit to metadata listed on or after the specified start time. any day/time
end[time] 2016-06-27T00:00:00 Limit to metadata listed on or before the specified end time. any day/time
Metric constraints
metric of choice +
_lt,_le,_gt,_ge,_eq,_ne		 sample_rms_ge=1000
percent_availability_eq=99.9		 Filter the data based on a quality control metric of your choosing.
Click the green button below for a list and description of all available metrics.		 None String
SUBMETRIC CASES
transfer_func-gain_ratio_lt=1
transfer_func-phase_diff_lt=-0.05
transfer_func-ms_coherence_gt=0.90		 transfer_func is an example of a metric that is a composite of submetrics (e.g., gain_ratio). To specify a submetric, use a hyphen (-) to separate metric from submetric. None String
noise_mode_diff +
_lt,_le,_gt,_ge		 noise_mode_diff_lt=hnm-15,0.001,100.0
noise_mode_diff_gt=lnm+15,0.001,100.0
noise_mode_diff_gt=lnm+15,1000s,0.01s		 Filter data based on decibels from the new LNM and/or the new HNM within a frequency or period range. None String

Pass/Fail options
nomeasurements reject If pass, records that do not contain a measurement value for the requested metric(s) are flagged as “pass” and are therefore included in the passing section of the response.
If reject, records that do not contain a value for the requested metric(s) are flagged as “fail” and are therefore included in the rejection log of the response		 pass String
pass any If all, a record must pass each and every requested metric in order to be included in the passing set of records of the response.
If any, a record needs to pass one or more requested metric in order to be included in the passing set of records of the response		 all String
Other options: these are passive options, passed through in the response but otherwise unused
nodata 404 Specify which HTTP status code is returned when no data is found.1 204 204 or 404

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. To force an empty query response to display an error message, add nodata=404 to the URL.

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

Wildcards

Wildcards
The question mark ? represents any single character (exactly one), while the asterisk * represents zero or more characters.

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.

IRISWS rrds web service