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.
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.
- radial geographic
- rectangular geographic with time windows
- text output, with network level exclusion
- horizontal channels for subsetted TA data
Detailed Descriptions of each Query Parameter
|Empty/No parameters||submitting an empty query (e.g.
|Exclusion parameters||each parameter listed under “channel options” can be prefixed with a
|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
|cha[nnel]||BH1||Select one or more SEED channel codes. Accepts wildcards and lists.||any||string|
|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|
|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
|minradius||19.0||Specify minimum distance from the geographic point defined by
|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
|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
|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|
minradius work together to define a radial boundary.
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 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=geocsv, then a simple
| separated table is returned. Note,
format=text is not available for
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:
- Instrument (description)
- Scale, ScaleFreq, ScaleUnits, SampleRate
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.
Retrieve the WADL associated with this service:
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
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:
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:
Please send an email report of which service you were using, your URL query, and any error feedback to:
data-help AT earthscope.org
We will address your issue as soon as possible.