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] [temporal-constraints] [value-constraints] [output-format] [sorting-options]

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)
temporal-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 >]

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 clock locked daily counts for station ANMO, channel BHZ.00 for the first two months of 2013 where the count value is less than 4000

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 for a specified date
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

Metric

The metric parameter identifies which particular metric(s) will be queried for measurements. There are a number of metrics that are available in MUSTANG and these can be found by consulting the metrics service. In the URL, the parameter looks something like metric=sample_mean . Multiple metrics are supported, which will cause metrics for a given target to be grouped together in the output. For example: metric=max_gap,sample_snr will return results for both metrics.
parameter example values discussion
metric max_gap get values for the max_gap metric (largest gap length for day)
metric sample_snr get values for the sample_snr metric (signal-to-noise ratio)
metric sample_mean get values for the sample_mean metric (average amplitude value for day)
Target

The target parameter allows individual targets to be named directly (for many targets, or for all targets that match a certain condition, see the examples).

Each target is identified using a SNCLQ, which has five components, in N.S.L.C.Q order:
  • Network – a SEED network code – ex. IU – or IRIS Virtual Network Code – ex. _GSN
  • Station – a SEED station code – ex. ANMO
  • Location – a SEED location code – ex. 00
  • Channel – a SEED channel code – ex. BH1
  • Quality – an IRIS data quality flag – M (typical), Q, R, or D
These are separated by a period (”.”). For example: target=IU.ANMO.00.BH1.M
For multiple targets, list the terms as a comma-separated list. For example: target=IU.ANMO.00.BH1.M,IU.ANMO.00.BH2.M
Blank location codes are specified using dash characters (”—”). For example: target=TA.109C.--.BHZ.M
Values can be wildcarded using the glob patterns ? and *.
target IU.ANMO.00.BH1.M target is network IU, station ANMO, location 00, channel BH1, quality M
target TA.M27K.--.BHZ.R target is network TA, station M27K, blank location code, channel BHZ, quality R
SNCLQ filter

These parameters select the targets that match the given SNCLQ components and can be used instead of using the target parameter. The five components are:
  • Network – a SEED network code or virtual network code – ex. net=_GSN
  • Station – a SEED station code – ex. sta=ANMO
  • Location – a SEED location code – ex. loc=00
  • Channel – a SEED channel code – ex. chan=BH1
  • Quality – a DMS quality flag – ex. qual=M
If all components are given then a single target will be identified. For example: net=IU&sta=ANMO&loc=00&chan=BH1&qual=M
If a virtual network code is specified, the sta term is ignored for that virtual network, but loc,cha,qual terms are still honored.
To request a blank location code, use dashes (”—”) loc=--. For example: net=US&sta=ACSO&loc=--&cha=BHZ
To select multiple instances of one SNCLQ component, comma-separate the terms. For example: chan=BH1,BH2 or sta=KDAK,PFO
Glob expressions may be used for wildcarding – ex. cha=BH?,H*
Regular expressions are also supported in matches, so an alternative way to select either of two channel orientations would be: chan=BH[12]
Note that not specifying a term has the same effect as wildcarding ‘*’ in the target. For example, leaving out loc and qual terms: net=US&sta=ACSO&cha=BHZ will select all locations.
net[work] IU Specify SEED network code
sta[tion] ANMO Specify SEED station code
loc[ation] 00 Specify SEED location code
cha[nnel] BH1 Specify SEED channel code
qua[lity] M Specify IRIS quality flag
Non-Standard Targets

Two metrics have non-standard target and SNCLQ filter formats : cross_talk and pressure_effects.

The cross_talk target takes the form of net.sta.loc.chan1:chan2.qual, where chan1 and chan2 are the two correlated channels.
example: target=IU.ANMO.00.BH1:BH2.M
The pressure_effects target takes the form of net.sta.loc1:loc2.chan1:chan2.qual, where loc1 is the location code of the LDO pressure channel, loc2 is the location code for the seismic channel, chan1 is LDO, and chan2 is one (or more) of the LH channels.
example: target=IU.ANMO.31:00.LDO:LHZ.M
You can do partial pair matching by specifying a single location or channel, matching to groups that contain just one of the terms – ex. target=IU.ANMO.31.LDO.M matches to anything with 31 in the location code and LDO in the channel pairing.
Temporal constraints

The following parameters impose various time constraints on the query. The list of metrics returned by the service will be restricted to include only those that have measurements in the appropriate time range. The time formatting is explained further detail in a separate section below.
timewindow 2010-09-15,2010-12-15 two comma-separated dates specify a time range that contain measurements, inclusive of the dates
start 2010-09-15T00:00:00 match to metrics with start times no earlier than indicated (much like the first term of timewindow)
startbefore 2011-05-21 get measurements starting before May 21, 2011
startafter 2001-05-21T09:00:00 get measurements starting after May 21, 2011, 0900 hours UTC
end 2010-12-15T00:00:00 match to metrics with end times no later than indicated (much like the second term of timewindow)
endbefore 2011-06-01T12:34:56.3321 get measurements ending before June 1, 2011, at a very specific time of day, UTC
endafter 2011-06-30 get measurements ending after June 30, 2011
Value constraints

Every metric has one or more fields for the measurements it contains, which we generically refer to here by name. The most common of these fields is value, but some metrics are more specific.

We can filter our query based on comparators to these value fields by adding the parameter name in combination with one of these operator suffixes to the URL:
  • _eq – Equal (the default if no extension is used)
  • _ne – Not equal
  • _gt – Greater than
  • _ge – Greater than or equal
  • _lt – Less than
  • _le – Less than or equal
Equality and inequality conditions can be repeated multiple times by repeating the parameter. For example: name=1&name=2 will return measurements where the named parameter has the values 1 or 2.

You can specify that the parameter has a value between 1 and 2, for example, by using: name_gt=1&name_lt=2

Missing values are specified with ‘NULL’ (in capitals), so you can exclude missing values with: name_ne=NULL

The value parameters available, and their data types, can be listed using the metrics service .
value 123 Match to measurements where ‘value’ is equal to the listed amount
value_eq 123 Match to measurements where ‘value’ is equal to the listed amount
value_ne 600 Exclude measurements where ‘value’ is a particular value
phase_diff_gt -60 Match to values where ‘phase_diff’ is greater than a particular value
count_ge 5 Match to values where ‘count’ is greater than or equal to a particular value
duration_lt 100 Match to values where ‘duration’ is less than a particular value
amplitude_le 6000000 Match to values where ‘amplitude’ is less than or equal to a particular value
Output Format

You can specify a number of different output formats. Each identifier is case-insensitive, so that format=xml is the same as format=XML.
format xml The data are returned as XML (the default).
format csv The data are returned as CSV (comma-separated values) with a content type of text/csv. Typically this means that the browser offers to save a file.
format text The data are returned as CSV (comma-separated values) with a content type of text/plain. Typically this means that the browser displays the data on-screen.
format json The data are returned in JSON format, with a similar structure to the XML format.
format jsonp A special variant of the JSON format output, which allows the inclusion of a second callback parameter, as shown next.
callback <function-name> Only used with JSONP calls, this specifies the name of a callback function that wraps or pads the JSON payload. – ex. callback=angular_callbacks._0
Sorting Options

This allows a named field to be used as the field to sort by. An underscore modifier is added to the name to indicate ascending or descending sort. The orderby parameter can be used multiple times to indicate secondary and tertiary sort order as well.
orderby start_asc Sort the results by start time in ascending order.
orderby sta_asc Sort the results by station name in ascending order.
orderby value_desc Sort the value field results in descending order, showing the largest values first.
Server Response

Currently, there is just one term that can be used to control the HTTP return code when no metrics are found.
nodata 404 Return a 404 HTTP code when no metrics are found.
nodata 204 Return a 204 HTTP code when no metrics are found.

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

MUSTANG measurements web service