SAGE Facility 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 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 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 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 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 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 quality indicator as part of a SNCLQ Filter when not using target. Metrics from our miniSEED archive are calculated using M quality data (with the exception of latency metrics which operate on R quality data). Metrics from our PH5 archive are calculated using D 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 or &orderby=sta,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. 204 204 or 404

Date Formats

Year, Month, Day in Month:

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)

Non-Standard Channel Names

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

  • cross_talk: net.sta.loc.chanA:chanB.qual
  • pressure_effects 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. This is not currently supported for MUSTANG metric names that begin with ‘ts_’.

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


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.

MUSTANG measurements web service