NSF SAGE Facility MUSTANG targets Web Service Documentation

Description

The targets web service returns a list of targets having measurements for the specified metric. Targets can be filtered by station, network, etc. This channel list can be passed to the measurements service using command line tools such as curl.

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

Query Usage

Start with base URL

https://service.earthscope.org/mustang/targets/1

append standard query pattern

/query? (metric) [snclq-filter] [server-response]

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

(..) required
[..] optional

Query parameters are joined by ampersands &, without blank space (see the sample queries).

Sample Queries

Which targets have STA/LTA measurements?
https://service.earthscope.org/mustang/targets/1/query?metric=max_stalta

Stations in the GSN, showing max_gap values?
https://service.earthscope.org/mustang/targets/1/query?metric=max_gap&network=_GSN

Detailed Descriptions of each Query Parameter

parameter examples discussion default type
metrics
metric sample_mean Retrieve targets having measurements for the specified metric. Select the Current list of all metrics button above for metrics names. string
channel options (SNCLQ filter)
net[work] IU Specify SEED network code. 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 any string
sta[tion] ANMO Specify SEED station code. Accepts wildcards and lists any string
loc[ation] 00 Specify SEED location code. Use -- for ‘blank’ location codes. Accepts wildcards and lists any string
cha[nnel] BH1 Specify SEED channel code. Accepts wildcards and lists any string
qua[lity] M Specify SEED quality indicator. Most metrics are calculated using M quality data. (Latency metrics operate on D and R quality data.) Accepts wildcards and lists any string
server response
nodata 404 Specify which HTTP status code is returned when no results are found. 204 204 or 404

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.

MUSTANG targets web service