Help: station v.1

Description

Data Retrieval Methods

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 networks, stations, locations and channels. Wildcards are supported. Please visit the ph5ws-station service interface for parameter usage details.

• via HTTP POST: Submit a file to the service containing a list of the desired networks, stations, locations, channels, start-times and end-times. This service now supports wildcards. Detailed examples are shown at the bottom of this page.

• via web service clients: Dedicated clients that use the ph5ws-station service can be found on the Client list. In particular, the FetchMetadata script will request metadata from ph5ws-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.

Service Output

Information can be retrieved at different levels of detail

The ph5ws-station web service can return metadata 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 Format

FDSN StationXML

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

Text

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 level=network

#Network|Description|StartTime|EndTime|TotalStations
YW|Wavefields Community Demonstration Experiment|2016-06-18T00:00:00|2016-10-30T00:00:00|397

Sample text output for level=station

#Network|Station|Latitude|Longitude|Elevation|SiteName|StartTime|EndTime
YW|1001|36.62229742|-97.740955|322.23|1001|2016-06-21T16:43:57|2016-07-26T13:19:57
YW|1002|36.62230102|-97.73983085|322.25|1002|2016-06-21T00:00:00|2016-07-27T23:59:59
YW|1003|36.62231905|-97.7387067|322.38|1003|2016-06-21T00:00:00|2016-07-27T23:59:59

Sample text output for level=channel

#Network|Station|Location|Channel|Latitude|Longitude|Elevation|Depth|Azimuth|Dip|SensorDescription|Scale|ScaleFreq|ScaleUnits|SampleRate|StartTime|EndTime
YW|1001||DP1|36.62229742|-97.740955|322.23|0.0|0.0|90.0|FairfieldNodal node_5Hz|726189631.024|10.0|M/S|250.0|2016-06-21T16:43:57|2016-07-26T13:19:57
YW|1001||DP2|36.62229742|-97.740955|322.23|0.0|0.0|90.0|FairfieldNodal node_5Hz|726189631.024|10.0|M/S|250.0|2016-06-21T16:43:57|2016-07-26T13:19:57
YW|1001||DPZ|36.62229742|-97.740955|322.23|0.0|0.0|90.0|FairfieldNodal node_5Hz|726189631.024|10.0|M/S|250.0|2016-06-21T16:43:57|2016-07-26T13:19:57
YW|1002||DP1|36.62230102|-97.73983085|322.25|0.0|0.0|90.0|FairfieldNodal node_5Hz|726189631.024|10.0|M/S|250.0|2016-06-21T00:00:00|2016-07-27T23:59:59
YW|1002||DP2|36.62230102|-97.73983085|322.25|0.0|0.0|90.0|FairfieldNodal node_5Hz|726189631.024|10.0|M/S|250.0|2016-06-21T00:00:00|2016-07-27T23:59:59
YW|1002||DPZ|36.62230102|-97.73983085|322.25|0.0|0.0|90.0|FairfieldNodal node_5Hz|726189631.024|10.0|M/S|250.0|2016-06-21T00:00:00|2016-07-27T23:59:59
YW|1003||DP1|36.62231905|-97.7387067|322.38|0.0|0.0|90.0|FairfieldNodal node_5Hz|726189631.024|10.0|M/S|250.0|2016-06-21T00:00:00|2016-07-27T23:59:59
YW|1003||DP2|36.62231905|-97.7387067|322.38|0.0|0.0|90.0|FairfieldNodal node_5Hz|726189631.024|10.0|M/S|250.0|2016-06-21T00:00:00|2016-07-27T23:59:59
YW|1003||DPZ|36.62231905|-97.7387067|322.38|0.0|0.0|90.0|FairfieldNodal node_5Hz|726189631.024|10.0|M/S|250.0|2016-06-21T00:00:00|2016-07-27T23:59:59

format=text is not available for level=response

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=Y*, net=*W, chan=D*Z or chan=DP?.

Lists

Users can specify multiple networks, stations, channels or locations in their search criteria by providing comma separated list. For example: sta=1001,1002.

Geographic searches

Searches may be limited geographically, either by specifying a bounding “rectangle” of minimum and maximum latitudes and longitudes, or by specifying a bounding circle, using a minimum/maximum radius around a latitude/longitude coordinate. These two types of searches are exclusive. All values are specified using ± decimal degrees.

Using latitude / longitude boundaries (Bounding Rectangle)

The following four parameters work together to search within a bounding rectangle: minlatitude, maxlatitude, minlongitude, maxlongitude. All four parameters are optional. The bounding box will cross the ±180° meridian when minlongitude > maxlongitude.

Example
.../query?minlatitude=36.0&maxlatitude=37.0&minlongitude=-99.0&maxlongitude=-97.0

Using a radial boundary (Bounding Circle)

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

Examples
.../query?latitude=46.0&longitude=-120.0&maxradius=10
.../query?latitude=46.0&longitude=-120.0&minradius=1.0&maxradius=10.0

Temporal searches

starttime, endtime

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.

Examples of POST queries

The text of an example selection file, submitted using HTTP POST, might be called station.request and look something like:

$ cat station.request
level=channel
reportnum=16-015
minlat=36
maxlat=37
minlon=-99
maxlon=-97
YW 1001 -- DPZ 2016-06-21T16:43:57 2016-07-26T13:19:57
YW 1002 -- DP? 2016-06-21T16:43:57 2016-07-26T13:19:57
YW 1003 -- DPZ 2016-06-21T16:43:57 2016-07-26T13:19:57

wget and curl

Requests can be made with a selection file (station.request, in these examples) and either the wget or curl unix command line utilities. Either of the commands below will POST the selection file to the server and save the results in a text file named station.result

$ wget --post-file=station.request -O station.result http://service.iris.edu/ph5ws/station/1/query

$ curl --data-binary @station.request -o station.result http://service.iris.edu/ph5ws/station/1/query

Here is the equivalent request using query parameters instead of a selection file…

$ curl -o station.result "http://service.iris.edu/ph5ws/station/1/query?level=channel&reportnum=16-015&net=YW&sta=1001,1002,1003&cha=DP?&loc=--&starttime=2016-06-21T16:43:57&endtime=2016-07-26T13:19:57&minlat=36&maxlat=37&minlon=-99&maxlon=-97"

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