Help: station v.1

Description

from obspy.clients.fdsn import Client
client = Client("EARTHSCOPE")

from obspy.clients.fdsn import Client
client = Client("https://service.earthscope.org/")

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

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.earthscope.org/fdsnws/station/1/query

$ curl -L --data-binary @station.request -o station.txt http://service.earthscope.org/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?