SAGE Facility 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|geocsv>] 

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 1001 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, text, and geocsv. 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, geocsv, or xml. If format=xml or format is not specified, then the results will be returned in FDSN StationXML format. When format=text or format=geocsv then a simple | separated table is returned. Note, format=text and format=geocsv 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, this web service return an HTTP code of 404 (rather than 204) when a request is “successful”, but there were no matching results. If 204 is chosen and no results are found, a web browser will not refresh its previous results. When 404 is used, a browser will update any headers (or tags) displayed on the screen, but will list no values. To force the service to return a 204, add the query parameter &nodata=204.

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


Problems with this service?

Please send an email report of which service you were using, your URL query, and any error feedback to:
data-help@earthscope.org
We will address your issue as soon as possible.

PH5WS station web service