IRIS DMC PH5WS station Web Service Documentation

Description

The ph5ws-station web service returns PH5 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, and geographic regions.

This service is an implementation of the FDSN web service specification version 1.

Below is a full list of service parameters and their usage.

Query Usage

/query? [channel-identifiers] [geographic-constraints] [time-constraints] [misc-parameters] [nodata=404]

where

channel-identifiers 	::  [ [network=<network>] or [reportnum=<reportnum>] ] [station=<station>]
                            [location=<location>] [channel=<channel>] [component=<componentid>]
                            [receiver=<receiverid>] [arrayid=<arraynumber>]
geographic-constraints 	::  [boundaries-rect] OR [boundaries-circ]
    boundaries-rect 	::  [minlatitude=<degrees>] [maxlatitude=<degrees>] [minlongitude=<degrees>]
                            [maxlongitude=<degrees>]
    boundaries-circ     ::  [latitude=<latitude>] [longitude=<longitude>] [maxradius=<degrees>]
                            [minradius=<degrees>]
time-constraints 	::  [starttime=<date>] [endtime=<date>]
misc-parameters 	::  [level=<station|network|channel|response>] [format=<xml|text>] 

Each parameter-value pair should be separated by an ampersand & and with no space.

Query POST Usage

Alternatively, instead of providing parameter-value pairs in the URL, a file containing a selection list can be POSTed to this service.

level=<network | station | channel | response>
format=<xml | text>
minlatitude=<degrees>
maxlatitude=<degrees>
minlongitude=<degrees>
maxlongitude=<degrees>
<network> <station> <location> <channel> <starttime> <endtime>
...

The parameters network, station, location, channel, starttime, and endtime are included in the repeated lines for the selection file. Wildcards are acceptable for network, station, location, and channel. A simple * wildcard expression is valid for starttime and endtime in http POST requests, but expressions that include ? are not.

Parameter-value pairs should be listed at the top of the file and are entirely optional.

For additional details, including an example selection file, visit the Help section for this service.

Sample Queries

Detailed Descriptions of each Query Parameter

parameter examples discussion default type
FDSN options
start[time] 2016-06-21T16:43:57 Limit to metadata describing channels operating on or after the specified start time. any day/time
end[time] 2016-07-26T13:19:57 Limit to metadata describing channels operating on or before the specified end time. any day/time
Empty/No parameters submitting an empty query (e.g. .../query?) will return ALL stations at the default level.
net[work] YW Select one or more network codes. Can be SEED codes or data center defined codes. Accepts wildcards and lists. any string
sta[tion] 1001 Select one or more SEED station codes. Accepts wildcards and lists. any string
loc[ation] 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] DPZ Select one or more SEED channel codes. Accepts wildcards and lists. any string
report[num] 16-015 Select one or more report-num codes. Accepts wildcards and lists. (Synonymous with Network) any string
component 1 Select one or more component id. Accepts wildcards and lists. (Synonymous with Channel) any string
receiver 1003 Select one or more receiver id. Accepts wildcards and lists. any string
array[id] 001 Specifies the array id that the station belongs to. Accepts wildcards and lists. any integer
BOX search terms incompatible with RADIAL search
minlat[itude] 36.0 Southern boundary. -90° degrees
maxlat[itude] 37.0 Northern boundary. 90° degrees
minlon[gitude] -99.0 Western boundary. -180° degrees
maxlon[gitude] -97.0 Eastern boundary. 180° degrees
RADIAL search terms incompatible with BOX search
lat[itude] 36 Specify the central latitude point. degrees
lon[gitude] -98 Specify the central longitude point. degrees
maxradius 5 Specify maximum distance from the geographic point defined by latitude and longitude. degrees
minradius 0 Specify minimum distance from the geographic point defined by latitude and longitude. 0 degrees
level channel Specify level of detail using network, station, channel,or response. station level
format text Specify output format. Valid formats include xml and text. xml format
nodata 404 Specify which HTTP status code is returned when no data is found.1 204 204 or 404

1 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, then a simple | separated table is returned. Note, format=text is not available for level=response.

Level

Level specifies the level of detail returned within the returned XML.


WADL

Retrieve the WADL associated with this service:

application.wadl


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

Glob Expressions

Wildcards
The question mark ? represents any single character (exactly one), while the asterisk * represents zero or more characters. These wildcards work when specifying a target, but not when specifying a SNCLQ filter.

Requests that return no result

By default, FDSN services return an HTTP code of 204 when a request is “successful”, but there were no matching results. This behavior allows automated systems to know the difference between a successful request (with no data) from an incorrect request (bad parameter names, invalid URL, etc). Since no content is returned, the page on the web browser will not change. To force the service to return a 404, add the query parameter nodata=404.

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

PH5WS station web service