IRIS DMC MUSTANG metrics Web Service Documentation

Description

The metrics web service returns a manifest of metrics available, either from the system as a whole, or as pertains to a particular target or time frame.

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

Query Usage

start with base URL

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

append standard query pattern

/query? (metric) [targets | snclq-filter] [temporal-constraints] [output-format]

where

         metric :: (metric=<data_latency | max_gap | max_overlap | max_stalta | num_gaps | num_overlaps | percent_availability | etc.....>)
        targets :: [target=<N.S.L.C.Q>] (can be comma-separated)
   snclq-filter :: [net[work]=<network>] [sta[tion]=<station>] [loc[ation]=<location>] [chan[nel]=<channel>] [qual[ity]=<quality>]  (terms can be comma-separated)
temporal-constraints :: [timewindow=<date,date>] [start=<date>] [startbefore=<date>] [startafter=<date>] [end=<date>] [endbefore=<date>] [endafter=<date>] (date pattern defined below)
  output-format :: [output=< html | xml | xsd >]
server-response :: [nodata=< HTTP code >]

Sample Queries

_Provide a description of the max_gap metric_
http://service.iris.edu/mustang/metrics/1/query?metric=max_gap

What are all of the metrics available in MUSTANG?
http://service.iris.edu/mustang/metrics/1/query

What metrics are available for station IU.ADK? — output in XSD format
http://service.iris.edu/mustang/metrics/1/query?net=IU&sta=ADK&output=xsd

Detailed Descriptions of each Query Parameter

parameter examples discussion
Empty/No parameters .../metrics/query? Submitting an empty query will return ALL metrics, with the output defaulting to html
Metric

This parameter identifies a particular metric to show the measurements of.
There are a number of metrics that are available in MUSTANG and are best found by using the “empty query pattern shown above”:http://service.iris.edu/mustang/metrics/1/query
In the URL, the parameter looks something like metric=sample_mean
metric max_gaps reference for the max gaps metric
metric sample_snr reference for the signal to noise ratio metric
metric up_down_times reference for the channel up and down time metric
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
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
Output Format

output html Provides a human-readable description of each metric using HTML (the default).
output xml Provides metrics descriptions in XML format.
output xsd Provides an XML schema that describes the format in which measurements are encoded. This format is used by the measurements service.
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 metrics web service