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