Description
The measurements web service returns measurements for metrics relating to station data quality. This is the primary query interface for MUSTANG users.
Below is a full list of service parameters and their usage.
Query Usage
Start with base URL
https://service.earthscope.org/mustang/measurements/1
append standard query pattern
/query? (metric) [targets | snclq-filter] [time-constraints] [value-constraints] [output-format] [sorting-options] [server-response]
where
metric :: (metric=<data_latency | max_gap | max_overlap | max_stalta | num_gaps | num_overlaps |
percent_availability | etc.....>) (repeat with comma separation)
targets :: [target=<N.S.L.C.Q>] (repeat with comma separation)
snclq-filter :: [net[work]=<network>] [sta[tion]=<station>] [loc[ation]=<location>] [chan[nel]=<channel>]
[qual[ity]=<quality>] (each term repeats with comma separation)
time-constraints :: [timewindow=<date,date>] [start=<date>] [startbefore=<date>] [startafter=<date>]
[end=<date>] [endbefore=<date>] [endafter=<date>] (date pattern defined below)
value-constraints :: [name=<value>] [name_eq=<value>] [name_ne=<value>] [name_lt=<value>] [name_le=<value>]
[name_gt=<value> [name_ge=<value>]
output-format :: [format=< xml | csv | text | json | jsonp >] (output= is deprecated)
sorting-options :: [orderby=< field-name >_asc] [orderby=< field-name >_desc]
server-response :: [nodata=< HTTP code >]
(..) required
[..] optional
Query parameters are joined by ampersands &, without blank space (see the sample queries).
Sample Queries
- Get STA/LTA values for station ANMO, channel BHZ starting 2012-10-01 with ending time before the start of 2013
- Give me a columnar text representation of the daily sample mean of station COR, channel BHZ, location ID 00 for this time period
- Download a Comma Separated Value (CSV) list of daily “clock locked” counts for station ANMO, channel BHZ.00 for the first two months of 2013 where there were fewer than 4000 clock locks
- Get the percent availability for GSN stations on March 1, 2015
Detailed Descriptions of each Query Parameter
| parameter | examples | discussion | default | type |
|---|---|---|---|---|
| metrics | ||||
| metric | sample_mean |
Retrieve values for the metric(s) specified. Select the Current list of all metrics button above for metrics names. Accepts lists but not wildcards. | string | |
| channel options (target or SNCLQ filter) | ||||
| target | IU.ANMO.00.BH1.M |
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. See instructions for matching non-standard channel names for metrics cross_talk, pressure_effects and transfer_function. |
any | string |
| net[work] | IU |
Specify 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 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 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. See instructions for matching non-standard channel names for metrics cross_talk, pressure_effects and transfer_function. |
any | string |
| cha[nnel] | BH1 |
Specify channel code as part of a SNCLQ Filter when not using target.Accepts wildcards and lists and regular expression matching. See instructions for matching non-standard channel names for metrics cross_talk, pressure_effects and transfer_function. |
any | string |
| qua[lity] | M |
Specify quality indicator as part of a SNCLQ Filter when not using target. Metrics from our miniSEED archive are calculated using M quality data (with the exception of latency metrics which operate on R quality data). Metrics from our PH5 archive are calculated using D quality data. The URL Builder no longer includes a text box for specifying quality, defaulting to “any”.Accepts wildcards and lists and regular expression matching. |
any | string |
| time constraints | ||||
| timewindow | 2010-09-15,2010-12-15 |
Limit to 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 |
Limit to measurements on data starting on or after this date[time]. | any | date/time |
| startbefore | 2011-05-21 |
Limit to measurements on data starting before this date[time] | any | date/time |
| startafter | 2001-05-21T09:00:00 |
Limit to measurements on data starting after this date[time] | any | date/time |
| end | 2010-12-15T00:00:00 |
Limit to measurements on data ending before this date[time]. | any | date/time |
| endbefore | 2011-06-01T12:34:56.3321 |
Limit to measurements on data ending before this date[time]. | any | date/time |
| endafter | 2011-06-30 |
Limit to measurements on data ending after this date[time]. | any | date/time |
| value constraints | ||||
| name | 123 |
Limit to measurements with ‘name’ equal to the listed value where ‘name’ is any numerical or date[time] column name returned (e.g. value, start, lddate). Listing multiple value constraints (e.g. &value=123&start=2018-05-01) returns results that satisfy all constraints. |
number or date/time | |
| name_eq | 123 |
Limit to measurements with ‘name’ equal to the listed value where ‘name’ is any numerical or date[time] column name returned (e.g. value_eq, start_eq, lddate_eq). Listing multiple value constraints (e.g. &value_eq=123&start_eq=2018-05-01) returns results that satisfy all constraints. |
number or date/time | |
| name_ne | 600 |
Limit to measurements with ‘name’ not equal to the listed value where ‘name’ is any numerical or date[time] column name returned (e.g. value_ne, start_ne, lddate_ne). Listing multiple value constraints (e.g. &value_ne=600&lddate_ne=2018-05-01) returns results that satisfy all constraints. |
number or date/time | |
| name_gt | -60 |
Limit to measurements with ‘name’ greater than the listed value where ‘name’ is any numerical or date[time] column name returned (e.g. value_gt, start_gt, lddate_gt). Listing multiple value constraints (e.g. &value_gt=-60&start_gt=2018-01-01) returns results that satisfy all constraints. |
number or date/time | |
| name_ge | 5 |
Limit to measurements with ‘name’ greater than or equal to the listed value where ‘name’ is any numerical or date[time] metric value name returned (e.g. value_ge, start_ge, lddate_ge). Listing multiple value constraints (e.g. &value_ge=5&start_ge=2018-01-01) returns results that satisfy all constraints. |
number or date/time | |
| name_lt | 100 |
Limit to measurements with ‘name’ less than the listed value where ‘name’ is any numerical or date[time] column name returned (e.g. value_lt, start_lt, lddate_lt). Listing multiple value constraints (e.g. &value_lt=100&end_lt=2018-05-01) limits results to measurements that satisfy all constraints. |
number or date/time | |
| name_le | 6000000 |
Limit to measurements with ‘name’ less than or equal to the listed value where ‘name’ is any numerical or date[time] column name returned (e.g. value_le, start_le, lddate_le). Listing multiple value constraints (e.g. &value_le=600000&start_le=2018-01-01) returns results that satisfy all constraints. |
number or date/time | |
| output format | ||||
| format | text |
Specify the (case-insensitive) output format. Valid formats include xml, csv, text, json and jsonp. |
xml | string |
| callback | <function-name> |
When format=jsonp, this specifies the name of a callback function that wraps or pads the JSON payload (e.g. callback=angular_callbacks._0). |
string | |
| sorting options | ||||
| orderby | start |
Sort the results by column name. To specify the sort order (default is ascending), append _asc or _desc to the column name (e.g. orderby=start_asc). When multiple orderby specifications are included (e.g. &orderby=sta&orderby=start or &orderby=sta,start), sorting will be performed in the order listed.Accepts lists but not wildcards. |
string | |
| server response | ||||
| nodata | 404 |
Specify which HTTP status code is returned when no results are found. | 204 | 204 or 404 |
Date Formats
Year, Month, Day in Month:
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)
Non-Standard Channel Names
Three metrics have non-standard target and SNCLQ filter formats:
- cross_talk:
net.sta.loc.chanA:chanB.qual - pressure_effects and transfer_function:
net.sta.locA:locB.chanA:chanB.qual
and so require special instructions for matching during queries. (See the documentation for each of these metrics for channel naming details.)
Including the channel or location code pair in the channel options (e.g. II.EFI.30:10.LDO:LHZ.M) will match measurements with this channel or target name exactly.
Including a single location or channel code (e.g. II.EFI.30.LDO:LHZ.M) will match all measurements where that code is included in the pair (location code pairs 30:00 and 30:10 in the case of pressure_effects measurements for II.EFI).
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_’.
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.
