NSF SAGE Facility FDSNWS station Web Service Documentation

Description

The fdsnws-station web service returns station metadata in FDSN StationXML format v1.1 (schema here) or as delimited text. Results are available at multiple levels of granularity: network, station, channel and response.

Metadata may be selected based on channel descriptors, time ranges, geographic regions, and more.

This service is an implementation of the FDSN web service specification version 1.1.

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

Query Usage

To retrieve data from the station service, submit a request by either of the methods below:

  • via HTTP GET: Provide a series of parameter-value pairs in the URL that specify the start-time and end-time, along with the desired network(s), station(s), location(s) and channel(s). Please refer to the table below titled “Detailed Descriptions of each Query Parameter” for usage details. Each parameter-value pair should be separated by an ampersand &, and with no space. A GET request may take the following general form:
    /query? [channel-options] [time-constraints] [geographic-constraints] [miscellaneous] [nodata=404]

  • via HTTP POST: Submit an arbitrary selection list to the service. Please note that all parameters listed under the rectangular geographic constraints, radial geographic constraints, and miscellaneous sections of the Detailed Descriptions of each Query Parameter table on the main service documentation page may be submitted using either GET or POST methods. For additional details on constructing and submitting POST selection files, visit the POST Examples in the Help section.
  • via web service clients: Dedicated clients that use the fdsnws-station service can be found on the Client list. In particular, the FetchMetadata script will request metadata from fdsnws-station, parse the returned XML and print or save simple ASCII information; this script can be used as a starting point for creating customized metadata requests.

Sample Queries

Detailed Descriptions of each Query Parameter

parameter examples discussion default type
channel options
Empty/No parameters submitting an empty query (e.g. .../query?) will return ALL stations at the default level.
Exclusion parameters each parameter listed under “channel options” can be prefixed with a - (minus) sign to exclude certain metadata from a request.
net[work] IU Select one or more network codes. Can be SEED codes or data center defined codes. Accepts wildcards and lists. any string
sta[tion] ANMO Select one or more SEED station codes. Accepts wildcards and lists. any string
loc[ation] 00 Select one or more SEED location identifier. Use -- for “Blank” location IDs (ID’s containing 2 spaces). Accepts wildcards and lists. any string
cha[nnel] BH1 Select one or more SEED channel codes. Accepts wildcards and lists. any string
time constraints
start[time] 2001-12-19T00:00:00 Limit to metadata describing channels operating on or after the specified start time. any day/time
end[time] 2012-12-31T23:59:59 Limit to metadata describing channels operating on or before the specified end time. any day/time
startbefore 2001-12-31T00:00:00 Limit to metadata epochs starting before specified time. Applied to channel epochs. any day/time
startafter 2005-12-31T00:00:00 Limit to metadata epochs starting after specified time. Applied to channel epochs. any day/time
endbefore 2005-12-31T00:00:00 Limit to metadata epochs ending before specified time. Applied to channel epochs. any day/time
endafter 2005-12-31T00:00:00 Limit to metadata epochs ending after specified time. Applied to channel epochs. any day/time
rectangular geographic constraints
minlat[itude] 15.5 Southern boundary. -90° degrees
maxlat[itude] 25.0 Northern boundary. 90° degrees
minlon[gitude] -170.0 Western boundary. -180° degrees
maxlon[gitude] 170.0 Eastern boundary. 180° degrees
radial geographic constraints
lat[itude] 35.0 Specify the central latitude point1. 0 degrees
lon[gitude] 170.0 Specify the central longitude point1. 0 degrees
maxradius 20.0 Specify maximum distance from the geographic point defined by latitude and longitude1. degrees
minradius 19.0 Specify minimum distance from the geographic point defined by latitude and longitude1. 0 degrees
miscellaneous
sensor STS-2 Select matching sensor descriptions. Sub-string match is case-insensitive and may be specified with wildcards and lists. The match is against the string in the Sensor::Description schema location. any string
level channel Specify level of detail using network, station, channel,or response2. station level
includerestricted TRUE Specify whether results should include information relating to restricted channels. true Boolean
includeavailability TRUE Specify if results should include information about time series data availability at the channel level. false Boolean
includecomments FALSE Specify if results should include station and channel comments. true Boolean
updatedafter 2012-01-01 Limit to metadata updated after specified UTC date; updates are data center specific. any day/time
format text Specify output format. Valid formats include xml, text, and geocsv. xml format
matchtimeseries TRUE Retrieve only metadata that is likely to match available time series data false Boolean
nodata 404 Specify which HTTP status code is returned when no data is found.3 204 204 or 404

1 latitude, longitude, maxradius and minradius work together to define a radial boundary.

2 When level=response only 120,000 channel entries may be requested.

3 By default, the service returns a HTTP response code 204, which means the request was successful, but no data (no content) was retrieved. However, because there was no “error”, no error message is generated and it may appear that the browser did nothing. To force an empty query response to display an error message, add nodata=404 to the URL.

Output Format

Output may be text or xml. If format=xml or format is not specified, then the results will be returned in FDSN StationXML format. When format=text or format=geocsv, then a simple | separated table is returned. Note, format=text is not available for level=response

NOTE: In the 1.1 version of this service, networks, stations, and channels without an explicit EndTime are represented in the following way:

  • format=xml : the EndTime is OMITTED from the element
  • format=text : the EndTime field is EMPTY
  • format=geocsv : the EndTime field is EMPTY
    In the future, clients should be prepared for omitted or blank field entries where they do not apply. Currently, such fields known to possibly have blank entries are:
  • StartTime
  • Instrument (description)
  • Scale, ScaleFreq, ScaleUnits, SampleRate

Level

Level specifies the level of detail returned within the returned XML. ‘network’ is the highest level, followed by ‘station’. To see channels within stations, level=‘channel’ is used. The most detailed level is ‘response’, which provides details to permit signal processing and proper conversion of digital readings to physical measurement.


WADL

Retrieve the WADL associated with this service:

application.wadl


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

Exclusions

A single dash ‘-’ may be prefixed to a single element to designate exclusion of that element from a selected set. The following example would remove all BHZ channels along with all 00 and 10 locations: channel=B*,-BHZ&location=-00,-10

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.

FDSNWS station web service