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.
start with base URL
append standard query pattern
/query? (metric) [targets | snclq-filter] [temporal-constraints] [value-constraints] [output-format] [sorting-options]
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) temporal-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 >]
Query parameters are joined by ampersands &, without blank space (see the 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 clock locked daily counts for station ANMO, channel BHZ.00 for the first two months of 2013 where the count value is less than 4000
- Get the percent availability for GSN stations for a specified date
Detailed Descriptions of each Query Parameter
The metric parameter identifies which particular metric(s) will be queried for measurements. There are a number of metrics that are available in MUSTANG and these can be found by consulting the metrics service. In the URL, the parameter looks something like
||get values for the max_gap metric (largest gap length for day)|
||get values for the sample_snr metric (signal-to-noise ratio)|
||get values for the sample_mean metric (average amplitude value for day)|
The target parameter allows individual targets to be named directly (for many targets, or for all targets that match a certain condition, see the examples).
Each target is identified using a SNCLQ, which has five components, in N.S.L.C.Q order:
For multiple targets, list the terms as a comma-separated list. For example:
Blank location codes are specified using dash characters (”—”). For example:
Values can be wildcarded using the glob patterns ? and *.
||target is network IU, station ANMO, location 00, channel BH1, quality M|
||target is network TA, station M27K, blank location code, channel BHZ, quality R|
These parameters select the targets that match the given SNCLQ components and can be used instead of using the
If a virtual network code is specified, the
To request a blank location code, use dashes (”—”)
To select multiple instances of one SNCLQ component, comma-separate the terms. For example:
Glob expressions may be used for wildcarding – ex.
Regular expressions are also supported in matches, so an alternative way to select either of two channel orientations would be:
Note that not specifying a term has the same effect as wildcarding ‘*’ in the target. For example, leaving out loc and qual terms:
||Specify SEED network code|
||Specify SEED station code|
||Specify SEED location code|
||Specify SEED channel code|
||Specify IRIS quality flag|
Two metrics have non-standard target and SNCLQ filter formats :
You can do partial pair matching by specifying a single location or channel, matching to groups that contain just one of the terms – ex.
The following parameters impose various time constraints on the query. The list of metrics returned by the service will be restricted to include only those that have measurements in the appropriate time range. The time formatting is explained further detail in a separate section below.
||two comma-separated dates specify a time range that contain measurements, inclusive of the dates|
||match to metrics with start times no earlier than indicated (much like the first term of
||get measurements starting before May 21, 2011|
||get measurements starting after May 21, 2011, 0900 hours UTC|
||match to metrics with end times no later than indicated (much like the second term of
||get measurements ending before June 1, 2011, at a very specific time of day, UTC|
||get measurements ending after June 30, 2011|
Every metric has one or more fields for the measurements it contains, which we generically refer to here by
We can filter our query based on comparators to these value fields by adding the parameter
You can specify that the parameter has a value between 1 and 2, for example, by using:
Missing values are specified with ‘NULL’ (in capitals), so you can exclude missing values with:
The value parameters available, and their data types, can be listed using the metrics service .
||Match to measurements where ‘value’ is equal to the listed amount|
||Match to measurements where ‘value’ is equal to the listed amount|
||Exclude measurements where ‘value’ is a particular value|
||Match to values where ‘phase_diff’ is greater than a particular value|
||Match to values where ‘count’ is greater than or equal to a particular value|
||Match to values where ‘duration’ is less than a particular value|
||Match to values where ‘amplitude’ is less than or equal to a particular value|
You can specify a number of different output formats. Each identifier is case-insensitive, so that
||The data are returned as XML (the default).|
||The data are returned as CSV (comma-separated values) with a content type of text/csv. Typically this means that the browser offers to save a file.|
||The data are returned as CSV (comma-separated values) with a content type of text/plain. Typically this means that the browser displays the data on-screen.|
||The data are returned in JSON format, with a similar structure to the XML format.|
||A special variant of the JSON format output, which allows the inclusion of a second
||Only used with JSONP calls, this specifies the name of a callback function that wraps or pads the JSON payload. – ex.
This allows a named field to be used as the field to sort by. An underscore modifier is added to the name to indicate ascending or descending sort. The orderby parameter can be used multiple times to indicate secondary and tertiary sort order as well.
||Sort the results by start time in ascending order.|
||Sort the results by station name in ascending order.|
||Sort the value field results in descending order, showing the largest values first.|
Currently, there is just one term that can be used to control the HTTP return code when no metrics are found.
||Return a 404 HTTP code when no metrics are found.|
||Return a 204 HTTP code when no metrics are found.|
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
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
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
The question mark
? represents any single character (exactly one), while the asterisk
* represents zero or more characters.
Multiple items may also be retrieved using a comma separated list. Wildcards may be included in the list. For example, with channel codes: