NSF SAGE

NSF SAGE Facility MUSTANG metrics Web Service Documentation

Service interface URL builder Help Revisions

Description

URL Builder

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

https://service.earthscope.org/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

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:
[email protected]
We will address your issue as soon as possible.

MUSTANG metrics web service