IRIS DMC MUSTANG targets Web Service Documentation

Description

The targets web service returns a list of targets for the given metric. Targets can be filtered by station, network, etc. The list can then be provided as a constraint when calling the measurements service.

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

Query Usage

start with base URL

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

append standard query pattern

/query? (metric) [snclq-filter]

where

         metric :: (metric=<data_latency | max_gap | max_overlap | max_stalta | num_gaps | num_overlaps | percent_availability | etc.....>)
   snclq-filter :: [net[work]=<network>] [sta[tion]=<station>] [loc[ation]=<location>] [chan[nel]=<channel>] [qual[ity]=<quality>]
server-response :: [nodata=< HTTP code >]

Sample Queries

Which targets have STA/LTA measurements?
http://service.iris.edu/mustang/targets/1/query?metric=max_stalta

Stations in the GSN, showing max_gap values?
http://service.iris.edu/mustang/targets/1/query?metric=max_gap&network=_GSN

Detailed Descriptions of each Query Parameter

parameter examples discussion
Metric

Constrain the targets list to a particular metric.
There are a number of metrics that are available in MUSTANG and are best found by using the metrics web service the URL, the parameter looks something like metric=sample_mean
metric max_gaps confine to the max gaps metric
metric sample_snr confine to the signal to noise ratio metric
metric up_down_times confine to the channel up and down time metric
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
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.

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 targets web service