The fdsnws-station web service returns station metadata in FDSN StationXML format (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.
Information can be retrieved at different levels of detail
The station web service can return station information at multiple levels of detail. The service response time and the volume of information returned are directly related to the requested level. With increasing detail the levels are:
|network||net||Network level information only, network description and station count.|
|station||sta||Station description, coordinates, time ranges and channel count. The default level.|
|channel||cha||Channel descriptions, coordinates, time ranges, instrument descriptions and channel sensitivity.|
|response||resp||Complete channel response information.|
The “FDSN StationXML“http://www.fdsn.org/xml/station/ format is an XML schema designed for exchanging station metadata.
When format=text, then a simple
| delimited table is returned. The results are not nearly as detailed as in the FDSN StationXML format, but they are more compact and easier to read.
Sample text output for
#Network | Description | StartTime | EndTime | TotalStations IU|Global Seismograph Network (GSN - IRIS/USGS)|1988-01-01T00:00:00|2500-12-12T23:59:59|252
Sample text output for
#Network | Station | Latitude | Longitude | Elevation | SiteName | StartTime | EndTime IU|ANMO|34.94591|-106.4572|1820.0|Albuquerque, New Mexico, USA|2008-06-30T20:00:00|2599-12-31T23:59:59 IU|ANMO|34.94591|-106.4572|1820.0|Albuquerque, New Mexico, USA|2008-06-30T00:00:00|2008-06-30T20:00:00
Sample text output for
#Network | Station | Location | Channel | Latitude | Longitude | Elevation | Depth | Azimuth | Dip | Instrument | Scale | ScaleFreq | ScaleUnits | SampleRate | StartTime | EndTime IU|ANMO|00|BH1|34.9459|-106.4572|1700.0|150.0|280.0|0.0|Geotech KS-54000 Borehole Seismometer|8.48507E8|0.02|M/S|20.0|1998-10-26T20:00:00|2000-10-19T16:00:00 IU|ANMO|00|BH2|34.9459|-106.4572|1700.0|150.0|10.0|0.0|Geotech KS-54000 Borehole Seismometer|8.71576E8|0.02|M/S|20.0|1998-10-26T20:00:00|2000-10-19T16:00:00
format=text is not available for level=response
The fdsnws-station service allows data selection using the following parameters:
- network1, station, location and channel
- time windowing
- geographic region, rectangular area or radius from a point
- metadata updated after a specific date
- time series data availability
see the service interface (link) for detailed usage
1 This service accepts virtual network names, also.
Metadata may be excluded by prefixing a - (minus) sign to values of network, station, location and channel. All excluded values are removed from the set selected by other, or default, criteria.
The default value for network, station, location and channel is “all”. With this in mind, if one or more exclusions are used with no positive selections the result is a the entire set without those explicitly excluded.
Using Wildcards and lists
Both wildcards and lists can be used for channel naming criteria:
The service supports the use of
* (asterisk) and
? (question mark) in specifying search criteria. The
* is used to indicate any combination of characters while
? is used to indicate one character only. They can be used at the beginning, middle or the end of the search criteria. Some examples:
Users can specify multiple networks, stations, channels or locations in their search criteria by providing comma separated list. For example:
Searches may be limited geographically, either by specifying a bounding “rectangle” of minimum and maximum latitudes and longitudes, or by specifying a bounding radius, using a minimum/maximum radius around a latitude/longitude pair. These two types of search are exclusive. All values are specified using ± decimal degrees.
Using latitude / longitude boundaries (Bounding Rectangle)
The following four parameters work together to specify a boundary rectangle:
maxlongitude. All four parameters are optional, but may not be mixed with the parameters used for searching within a defined radius. The bounding box will cross the ±180° meridian when minlongitude > maxlongitude.
Using a radial boundary (Bounding Radius)
The following four parameters work together to search within a great circle radius around a coordinate.
minradius. If any these parameters are used, all other (unspecified) parameters are assigned default values.
starttime, endtime, startbefore, endbefore, startafter, endafter
All of these criteria are applied to the channel epochs to limit the returned metadata. Even when the requested level is network or station, the test is applied to the channel epochs within the networks and stations. This means it is not possible to select network or station time ranges where there are no channels defined, but this situation rarely occurs and would be mostly meaningless from a data-use perspective.
Time series extents — that is, the time period over which each channel’s time-series data has been archived at IRIS — are available through this service. These can be used to limit the results, or may also be included within the results.
Some caveats associated with the time series availabilities:
- Extents are based upon when time series data first arrived until it was last received. There may be large data gaps that are not shown, so there is no guarantee that time series data will exist for the requested time period.
- Extents are not modified in real-time. The archive will likely be out of sync by up to a day, meaning:
- The service assumes that if channel data was archived within the last 36 hours, then data for the last 36 hours is available.
- Brand-new channels may not be reflected in the metadata results.
includeavailability=true will include a section in the XML that lists the time period for which archived data may exist. A section tagged
<DataAvailability> will appear as a child below the
<Channel> tags when data is available. For example:
<DataAvailability> <Extent start="1998-10-26T20:35:58" end="2013-03-08T12:00:00"/> </DataAvailability></pre>
end= extents refer to the times that data for this channel was first received and last received respectively.
matchtimeseries=true, the station service returns only metadata that is likely to match archived time-series data.
This will filter out channels where:
- timeseries data is not archived at the DMC
- timeseries data started arriving after the requested date-range
- timeseries data ceased to arrive before the requested date-range
Many time series channels are flowing into the DMC in near real-time. To match time series for requests near current time any channel that has arrived within the last 36 hours is treated as available through the current time.
matchtimeseries=true is selected, the time ranges of the returned meta-data do not guarantee waveform data availability. The information used to determine time series availability does not account for gaps in the time series.
includerestricted=false then the station service results will not include metadata for restricted channels.
Certain channels of time series data are not immediately publicly available. Metadata are still available for restricted channels and are included in the results. Restricted channels may not be relevant to all users, and may be removed from the results by adding
includerestricted=false to the query.
Learn more about restricted data here
Examples of POST queries
Requests submitted via HTTP POST allow for arbitrary combinations of network, station, location, channel and time window. All of the parameters that can be submitted with the GET method are allowed in POST with the following exceptions: startbefore, endbefore, startafter, endafter. The general form of a POST request is parameter=value pairs, one per line, followed by an arbitrary number of channel and time window selection lines:
parameter=<value> parameter=<value> parameter=<value> <network> <station> <location> <channel> <starttime> <endtime> <network> <station> <location> <channel> <starttime> <endtime> ...
Often such a POST request is created as a file and then an HTTP tool is used to submit the file to the service. The text of an example selection in a file named station.request could look like:
$ cat station.request level=channel format=text TA A25A -- BH? 2010-03-25T00:00:00 2010-04-01T00:00:00 IU ANMO * BH? 2010-03-25T00:00:00 2010-04-01T00:00:00 IU ANMO 10 HHZ 2010-03-25T00:00:00 2010-04-01T00:00:00 II KURK 00 BH? 2010-03-25T00:00:00 2010-04-01T00:00:00
Submitting POST request files via wget and curl
Requests can be made with a selection file (station.request in these examples) using either the
curl Unix command line utilities. The commands below will POST the selection file to the server and save the results in a text file named station.txt
$ wget --post-file=station.request -O station.txt http://service.iris.edu/fdsnws/station/1/query
$ curl -L --data-binary @station.request -o station.txt http://service.iris.edu/fdsnws/station/1/query
We recommend always using the
-L option to allow curl to follow HTTP redirections specified by our systems. The DMC uses HTTP redirection during maintenance to keep servicing requests.
curl, you may wish to use the
-f option. This will cause
curl to return an exit code of 22 if data is not found or the request is improperly formatted. See http://curl.haxx.se/docs/manpage.html for more information.