Description
The metrics web service returns an overview of all metrics requested that are either generally available, or that have measurements for the channels or times specified.
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] [time-constraints] [output-format] [server-response]
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) time-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 >]
(..) required
[..] optional
Query parameters are joined by ampersands &, without blank space (see the sample queries).
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 | default | type |
---|---|---|---|---|
Empty/No parameters | .../metrics/query? |
Submitting an empty query will return ALL metrics, with the output defaulting to html . |
||
metrics | ||||
metric | sample_mean |
Summarize requested metrics. 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. |
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. |
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. |
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.) Accepts wildcards and lists and regular expression matching. |
any | string |
time constraints | ||||
timewindow | 2010-09-15,2010-12-15 |
Display overview if metric has 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 |
Display overview if metric has measurements on data starting on or after this date[time]. | any | date/time |
startbefore | 2011-05-21 |
Display overview if metric has measurements on data starting before this date[time] | any | date/time |
startafter | 2001-05-21T09:00:00 |
Display overview if metric has measurements on data starting after this date[time] | any | date/time |
end | 2010-12-15T00:00:00 |
Display overview if metric has measurements on data ending before this date[time]. | any | date/time |
endbefore | 2011-06-01T12:34:56.3321 |
Display overview if metric has measurements on data ending before this date[time]. | any | date/time |
endafter | 2011-06-30 |
Display overview if metric has measurements on data ending after this date[time]. | any | date/time |
output format | ||||
format | text |
Specify the (case-insensitive) output format. Valid formats include html , xml and xsd . |
html | string |
server response | ||||
nodata | 404 |
Specify which HTTP status code is returned when no results are found. | 204 | 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
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_’.
Requests that return no result
By default, this web service return an HTTP code of 404 (rather than 204) when a request is “successful”, but there were no matching results. If 204 is chosen and no results are found, a web browser will not refresh its previous results. When 404 is used, a browser will update any headers (or tags) displayed on the screen, but will list no values. To force the service to return a 204, add the query parameter &nodata=204
.
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.