SAGE Facility PH5WS availability Web Service Documentation

Description

The ph5ws-availability web service returns detailed time span information of what timeseries data is available at the DMC archive.

There are two service query methods:

/extent

Produces lists of available time extents (earliest to latest) for selected channels (network, station, location and quality) and time ranges.

/query

Produces lists of contiguous time spans for selected channels (network, station, location, channel and quality) and time ranges.

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

Query Usage

/extent GET Usage

/extent? [channel-options] [time-constraints] [merge-options] [sort-options] [format-options] [misc-options] [nodata=404] 

where

channel-options    :: [net=<network>] [sta=<station>] [loc=<location>] [cha=<channel>] [quality=<quality>]
time-constraints   :: [starttime=<date>] [endtime=<date>]
merge-options      :: [merge=<samplerate|quality|overlap>] 
sort-options       :: [orderby=<nslc_time_quality_samplerate|timespancount|timespancount_desc|latestupdate|latestupdate_desc>]
format-options     :: [format=<text|geocsv|json|request>]
misc-options       :: [includerestricted=<true|false>] [limit=<number>]
passive-options    :: [nodata=<204|404>]

Query parameters are joined by ampersands ”&”, without blank space (see the sample queries).

/query GET Usage

/query? [channel-options] [time-constraints] [merge-options] [sort-options] [format-options] [misc-options] [nodata=404] 

where

channel-options    :: [net=<network>] [sta=<station>] [loc=<location>] [cha=<channel>] [quality=<quality>]
time-constraints   :: [starttime=<date>] [endtime=<date>]
merge-options      :: [merge=<samplerate|quality|overlap>] [mergegaps=<integer>]
sort-options       :: [orderby=<nslc_time_quality_samplerate|latestupdate|latestupdate_desc>]
format-options     :: [format=<text|geocsv|json|request>] [show=<latestupdate>]
misc-options       :: [includerestricted=<true|false>] [limit=<number>]
passive-options    :: [nodata=<204|404>]

Query parameters are joined by ampersands ”&”, without blank space (see the sample queries).

/query and /extent POST Usage

The /extent and /query methods can also be queried via HTTP POST. See Help

Sample Queries

Extent information for all network YW, station 1002 channels in text format
http://service.iris.edu/ph5ws/availability/1/extent?network=YW&station=1002

Available Data from network YB, station 10000, channel DPZ for a given time interval
http://service.iris.edu/ph5ws/availability/1/query?network=YB&station=10000&channel=DPZ&start=2009-07-17T05:59:00&end=2009-07-20T12:20:00

Detailed Descriptions of each Query Parameter

Common Parameters

/extent and /query accept these common parameters.

parameter values discussion default type
Channel contraints
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] 1002 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
quality D Select based on SEED quality codes D, M, Q, R. Wildcard * as well as a comma selected list are accepted any quality
Time constraints
start[time] 2016-06-21T16:59:08.890000 Limit to timespans on or after the specified start time. any day/time
end[time] 2016-07-27T01:10:08.890000 Limit to timespans before the specified end time. any day/time
Merge options
merge Merge rows by:
samplerate time spans from data with differing sample rates will be grouped together. If specified this field will be
quality time spans from data with differing quality codes will be grouped together. If specified this field will be omitted
overlap time spans from data that overlap will be merged together. This option does not apply to the extent method.
Sort Options (Incompatible with start and end options and virtual networks)
orderby Sort rows by:
nslc_time_quality_samplerate network, station, location, channel, time-range, quality, sample-rate (default)
latestupdate update-date (past to present), network, station, location, channel, time-range, quality, sample-rate
latestupdate_desc update-date (present to past), network, station, location, channel, time-range, quality, sample-rate
limit integer Limits output to this many rows. 0 or negative means unlimited. integer
includerestricted true If true, all available data is reported. If false, only data that can be download is reported. false true/false
format json Specify output format. Accepted values are text (the default), geocsv, json and request. text format (default) is meant to be human readable. request format can only available from the /extent method only and can be used directly in POST requests to the ph5ws-dataselect service. text string
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 an HTTP response code 204 if the request was successful, but no data (no content) was retrieved. In this situation 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.

The /extent method accepts these additional parameters:

Sort Options (Incompatible with start and end options and virtual networks)
orderby Sort rows by:
timespancount number of timespans (small to large), network, station, location, channel, time-range, quality, sample-rate
timespancount_desc number of timespans (large to small), network, station, location, channel, time-range, quality, sample-rate

The /query method accepts these additional parameters:

mergegaps 86400.0 (1 day) If set, merge time spans that are separated by the specified tolerance in seconds. Seconds, Float
show latestupdate If set to latestupdate, the latest times at which data contributing to the returned time spans were loaded into the
repository are included in the result. This option applies to all formats except request.
string

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

Restricted Data Access

For access to restricted data, requests should be sent to: service/ph5ws/availability/1/queryauth

Requests sent to this URL are authenticated via digest access authentication in order to establish the caller's credentials. For anonymous access, the user [email protected] and password anonymous may be used. This credential has identical data access permission as the regular submit path's: service/ph5ws/availability/1/query


Problems with this service?

Please send an email report of which service you were using, your URL query, and any error feedback to:
[email protected]
We will address your issue as soon as possible.

PH5WS availability web service