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
- radial geographic
http://service.iris.edu/fdsnws/station/1/query?latitude=-56.1&longitude=-26.7&maxradius=15&nodata=404
- rectangular geographic with time windows
…/query?startafter=2003-01-07&endbefore=2011-02-07&minlatitude=15&maxlatitude=55&minlongitude=170&maxlongitude=-170
- text output, with network level exclusion
…/query?network=S*,-SY&level=network&format=text
- horizontal channels for subsetted TA data
…/query?network=TA&station=A*&channel=BH?,-BHZ&level=channel&format=text
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 longitude 1. |
degrees | |
minradius | 19.0 | Specify minimum distance from the geographic point defined by latitude and longitude 1. |
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 response 2. |
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 elementformat=text
: the EndTime field is EMPTYformat=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:
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.