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
- rectangular geographic with time windows
http://service.iris.edu/ph5ws/station/1/query?starttime=2016-06-21T16:43:57&endtime=2016-07-26T13:19:57&minlat=36&maxlat=37&minlon=-99&maxlon=-97&network=YW&station=100?
- text output, with reportnum selection at the network level
…/query?reportnum=16-015&level=network&format=text
- geocsv output, with reportnum selection at the station level
…/query?reportnum=16-015&level=station&format=geocsv
- All DP channels, with subsetted YW data
…/query?network=YW&station=100?&channel=DP?&level=channel&format=text
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:
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:
[email protected]
We will address your issue as soon as possible.
