IRIS DMC MUSTANG measurements Web Service Documentation

Description

The measurements web service returns measurements for metrics relating to station data quality. This is the primary query interface for MUSTANG users.

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

Query Usage

Start with base URL

http://service.iris.edu/mustang/measurements/1

append standard query pattern

/query? (metric) [targets | snclq-filter] [time-constraints] [value-constraints] [output-format] [sorting-options] [server-response]

where

metric            ::  (metric=<data_latency | max_gap | max_overlap | max_stalta | num_gaps | num_overlaps | 
                      percent_availability | etc.....>) (repeat with comma separation)
targets           ::  [target=<N.S.L.C.Q>] (repeat with comma separation)
snclq-filter      ::  [net[work]=<network>] [sta[tion]=<station>] [loc[ation]=<location>] [chan[nel]=<channel>] 
                      [qual[ity]=<quality>]  (each term repeats with comma separation)
time-constraints  ::  [timewindow=<date,date>] [start=<date>] [startbefore=<date>] [startafter=<date>] 
                      [end=<date>] [endbefore=<date>] [endafter=<date>] (date pattern defined below)
value-constraints ::  [name=<value>] [name_eq=<value>] [name_ne=<value>] [name_lt=<value>] [name_le=<value>] 
                      [name_gt=<value>  [name_ge=<value>]
output-format     ::  [format=< xml | csv | text | json | jsonp >]   (output= is deprecated)
sorting-options   ::  [orderby=< field-name >_asc] [orderby=< field-name >_desc]
server-response   ::  [nodata=< HTTP code >]

(..) required
[..] optional

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

Sample Queries

  • Get STA/LTA values for station ANMO, channel BHZ starting 2012-10-01 with ending time before the start of 2013

http://service.iris.edu/mustang/measurements/1/query?metric=max_stalta&station=ANMO&channel=BHZ&start=2012-10-01&end=2013-01-01

  • Give me a columnar text representation of the daily sample mean of station COR, channel BHZ, location ID 00 for this time period

http://service.iris.edu/mustang/measurements/1/query?metric=sample_mean&sta=COR&cha=BHZ&loc=00&format=text&start=2012-10-01T00:00:00&end=2013-01-01T00:00:00

  • Download a Comma Separated Value (CSV) list of daily “clock locked” counts for station ANMO, channel BHZ.00 for the first two months of 2013 where there were fewer than 4000 clock locks

http://service.iris.edu/mustang/measurements/1/query?metric=clock_locked&sta=ANMO&cha=BHZ&loc=00&format=csv&start=2013-01-01&end=2013-03-01&value_lt=4000

  • Get the percent availability for GSN stations on March 1, 2015

http://service.iris.edu/mustang/measurements/1/query?metric=percent_availability&net=_GSN&start=2015-03-01&end=2015-03-02&format=text&orderby=target,start

Detailed Descriptions of each Query Parameter

parameter examples discussion default type
metrics
metric sample_mean Retrieve values for the metric(s) specified. Select the Current list of all metrics button above for metrics names. Accepts lists but not wildcards. string
channel options (target or SNCLQ filter)
target IU.ANMO.00.BH1.M SEED Network, Station, Channel, Location and Quality codes separated by periods. Use -- for ‘blank’ location codes. When using target to specify channel options, omit SNCLQ Filter parameters (network, station, location, channel and quality).

Accepts wildcards and lists. See instructions for matching non-standard channel names for metrics cross_talk, pressure_effects and transfer_function.
any string
net[work] IU Specify SEED network code as part of a SNCLQ Filter when not using target. If a virtual network code is specified, the sta[tion] term is ignored, but loc[ation, cha[nnel] and qual[ity] codes are honored.

Accepts wildcards and lists and regular expression matching.
any string
sta[tion] ANMO Specify SEED station code as part of a SNCLQ Filter when not using target.

Accepts wildcards and lists and regular expression matching.
any string
loc[ation] 00 Specify SEED location code as part of a SNCLQ Filter when not using target. Use -- for ‘blank’ location codes.

Accepts wildcards and lists and regular expression matching. See instructions for matching non-standard channel names for metrics cross_talk, pressure_effects and transfer_function.
any string
cha[nnel] BH1 Specify SEED channel code as part of a SNCLQ Filter when not using target.

Accepts wildcards and lists and regular expression matching. See instructions for matching non-standard channel names for metrics cross_talk, pressure_effects and transfer_function.
any string
qua[lity] M Specify SEED quality indicator as part of a SNCLQ Filter when not using target. Most metrics are calculated using M quality data. (Latency metrics operate on D and R quality data.) The URL Builder no longer includes a text box for specifying quality, defaulting to “any”.

Accepts wildcards and lists and regular expression matching.
any string
time constraints
timewindow 2010-09-15,2010-12-15 Limit to measurements on data starting on or after the start of the timewindow and ending before the end of the time window. any date/time
start 2010-09-15T00:00:00 Limit to measurements on data starting on or after this date[time]. any date/time
startbefore 2011-05-21 Limit to measurements on data starting before this date[time] any date/time
startafter 2001-05-21T09:00:00 Limit to measurements on data starting after this date[time] any date/time
end 2010-12-15T00:00:00 Limit to measurements on data ending before this date[time]. any date/time
endbefore 2011-06-01T12:34:56.3321 Limit to measurements on data ending before this date[time]. any date/time
endafter 2011-06-30 Limit to measurements on data ending after this date[time]. any date/time
value constraints
name 123 Limit to measurements with ‘name’ equal to the listed value where ‘name’ is any numerical or date[time] column name returned (e.g. value, start, lddate). Listing multiple value constraints (e.g. &value=123&start=2018-05-01) returns results that satisfy all constraints. number or date/time
name_eq 123 Limit to measurements with ‘name’ equal to the listed value where ‘name’ is any numerical or date[time] column name returned (e.g. value_eq, start_eq, lddate_eq). Listing multiple value constraints (e.g. &value_eq=123&start_eq=2018-05-01) returns results that satisfy all constraints. number or date/time
name_ne 600 Limit to measurements with ‘name’ not equal to the listed value where ‘name’ is any numerical or date[time] column name returned (e.g. value_ne, start_ne, lddate_ne). Listing multiple value constraints (e.g. &value_ne=600&lddate_ne=2018-05-01) returns results that satisfy all constraints. number or date/time
name_gt -60 Limit to measurements with ‘name’ greater than the listed value where ‘name’ is any numerical or date[time] column name returned (e.g. value_gt, start_gt, lddate_gt). Listing multiple value constraints (e.g. &value_gt=-60&start_gt=2018-01-01) returns results that satisfy all constraints. number or date/time
name_ge 5 Limit to measurements with ‘name’ greater than or equal to the listed value where ‘name’ is any numerical or date[time] metric value name returned (e.g. value_ge, start_ge, lddate_ge). Listing multiple value constraints (e.g. &value_ge=5&start_ge=2018-01-01) returns results that satisfy all constraints. number or date/time
name_lt 100 Limit to measurements with ‘name’ less than the listed value where ‘name’ is any numerical or date[time] column name returned (e.g. value_lt, start_lt, lddate_lt). Listing multiple value constraints (e.g. &value_lt=100&end_lt=2018-05-01) limits results to measurements that satisfy all constraints. number or date/time
name_le 6000000 Limit to measurements with ‘name’ less than or equal to the listed value where ‘name’ is any numerical or date[time] column name returned (e.g. value_le, start_le, lddate_le). Listing multiple value constraints (e.g. &value_le=600000&start_le=2018-01-01) returns results that satisfy all constraints. number or date/time
output format
format text Specify the (case-insensitive) output format. Valid formats include xml, csv, text, json and jsonp. xml string
callback <function-name> When format=jsonp, this specifies the name of a callback function that wraps or pads the JSON payload (e.g. callback=angular_callbacks._0). string
sorting options
orderby start Sort the results by column name. To specify the sort order (default is ascending), append _asc or _desc to the column name (e.g. orderby=start_asc). When multiple orderby specifications are included (e.g. &orderby=sta&orderby=start), sorting will be performed in the order listed.

Accepts lists but not wildcards.
string
server response
nodata 404 Specify which HTTP status code is returned when no results are found. 404 204 or 404

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

Non-Standard Channel Names

Three metrics have non-standard target and SNCLQ filter formats:

  • cross_talk: net.sta.loc.chanA:chanB.qual
  • pressure_efffects and transfer_function: net.sta.locA:locB.chanA:chanB.qual

and so require special instructions for matching during queries. (See the documentation for each of these metrics for channel naming details.)

Including the channel or location code pair in the channel options (e.g. II.EFI.30:10.LDO:LHZ.M) will match measurements with this channel or target name exactly.

Including a single location or channel code (e.g. II.EFI.30.LDO:LHZ.M) will match all measurements where that code is included in the pair (location code pairs 30:00 and 30:10 in the case of pressure_effects measurements for II.EFI).

Regular Expression Matching

Regular expressions are also supported in matching. The expression channel=BH[12] matches measurements having channels BH1 or BH2.

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

MUSTANG measurements web service