Help: station v.1

Description

Service Output

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:

Output Formats

FDSN StationXML

The FDSN StationXML format is an XML schema designed for exchanging station metadata.

Text

When format=text, then a simple vertial bar (|) 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. The very last field in the text is not followed by a delimiter. An empty field will have no characters or spaces entered but will be immediately followed by another delimiter, unless it is the last field.

Sample text output for level=network. (note the empty EndTime for network IU – this will occur if the network is permanent and still active)

#Network | Description | StartTime | EndTime | TotalStations
IU|Global Seismograph Network (GSN - IRIS/USGS)|1988-01-01T00:00:00||252

Sample text output for level=station. (note the empty EndTime on the first line – this will occur if the station is still active in that configuration)

#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|
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 level=channel

#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

Metadata selection

The fdsnws-station service allows data selection using the following parameters:

• network¹, 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

¹ This service accepts virtual network names, also.

Metadata exclusion

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.

Examples
.../query?network=-SY&level=station
.../query?network=TA&channel=BH?,-BHZ&level=channel

Using Wildcards and lists

Both wildcards and lists can be used for channel naming criteria: network, station, location, channel.

Wildcards

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:
net=I*, net=*I, chan=B*Z or chan=B?Z.

Lists

Users can specify multiple networks, stations, channels or locations in their search criteria by providing comma separated list. For example: sta=ANMO,ANTO or chan=BHZ,BH1.

Geographic search

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: minlatitude, maxlatitude, minlongitude, 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.

Example
.../query?minlatitude=45&maxlatitude=60&minlongitude=-150&maxlongitude=-148

Using a radial boundary (Bounding Radius)

The following four parameters work together to search within a great circle radius around a coordinate. latitude, longitude, maxradius, and minradius. If any these parameters are used, all other (unspecified) parameters are assigned default values.

Examples
.../query?latitude=40.0&longitude=-100.0&maxradius=2
.../query?latitude=40.0&longitude=-100.0&minradius=18.0&maxradius=20

Temporal searches

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.

If your search criteria happen to fall on the boundary of two channel epochs, the service will only return the epoch with the earlier start time by default.

Data Availability

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

Specifying 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>

The start= and end= extents refer to the times that data for this channel was first received and last received respectively.

matchtimeseries

When 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.

Note: When 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

When 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 wget or 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.

When using 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.

Problems with this service?