Description
The irisws-fedcatalog web service returns selected time series channels from across multiple FDSN data centers. The combined catalog of channels is updated daily from each contributing data center.
This interface is primarily designed for discovery of data channels and subsequent requesting of time series using FDSN Web Service interfaces. The service is also capable of removing overlap from the channel list when the same channels are available from multiple data centers, avoiding the request and processing of duplicate data.
This interface is designed to support client-side federated data access.
FDSN Data Centers
A list of FDSN data centers (returns JSON) contributing to the combined catalog is available in JSON format and includes web service endpoints at each data center.
For data centers that wish to have their center included in the EarthScope Federator system see the new data centers section.
Below is a full list of service parameters and their usage.
Query Usage
/query? [service-options] [active-options] [passive-options] [nodata=404]
where
service-options :: [targetservice=<station|dataselect>][format=<request|text>][includeoverlaps=<true|false>]
active-options :: [channel-options] [map-constraints] [time-constraints]
channel-options :: [net=<network>] [sta=<station>] [loc=<location>] [cha=<channel>]
map-constraints :: [boundaries-rect] OR [boundaries-circ]
boundaries-rect :: [minlatitude=<degrees>] [maxlatitude=<degrees>] [minlongitude=<degrees>] [maxlongitude=<degrees>]
boundaries-circ :: [latitude=<degrees>] [longitude=<degrees>] [maxradius=<number>] [minradius=<number>]
time-constraints :: [starttime=<date>] [endtime=<date>] [startbefore=<date>] [startafter=<date>]
[endbefore=<date>] [endafter=<date>] [updatedafter=<date>]
passive-options :: [includerestricted=<true|false>] [includeavailability=<true|false>] [matchtimeseries=<true|false>]
[longestonly=<true|false>] [quality=<D|R|Q|M|B>] [level=<net|sta|cha|resp>]
[minimumlength=<number>]
Query parameters are joined by ampersands ”&”, without blank space (see the sample queries).
In the context of the irisws-fedcatalog service, active options refer to parameters that filter the results returned by the service based on the value(s) of the parameter(s). In contrast, passive options are parameters that do not filter results and are simply passed from command line to output.
POST Usage
Alternately, instead of providing parameter-value pairs in the URL, a file containing a selection list can be POSTed to this service. This is the same method used with the fdsnws-station and fdsnws-dataselect webservices. For additional details, including an example selection file, visit the Help section.
quality=<D|R|Q|M|B> minimumlength=<seconds> longestonly=<true|false> <Network> <Station> <Location> <Channel> <StartTime> <EndTime> ...
quality, minimumlength, and longestonly are optional parameter-value pairs. Wildcards are acceptable for Network, Station, Location, and Channel. Click here for time format details.
Datacenters Usage
In addition to “/query”, a “/datacenters” endpoint is available for information on the set of data centers known to the fedcatalog service. The FDSN services hosted by these data centers are the source of the fedcatalog’s daily data harvest: see the “Service URLs” field in the /datacenters response. Included in the “Service URLs” field is the FDSN station URL used by the fedcatalog for iterating network, station, and channel data per repository.
Please note the “Name” field returned by the datacenters endpoint. This is the identifier which can in turn be used in the “/query” endpoint for limiting fedcatalog searches to a subset of repositories (see the “datacenter” parameter of the “/query” endpoint above).
/datacenters? [service-options]
where
service-options :: [format=<json|text|html>]
Sample Queries
*rectangular geographic search with wildcard channel
http://service.iris.edu/irisws/fedcatalog/1/query?net=TA&minlat=34&maxlat=38&maxlon=-93&minlon=-85&cha=?HZ
*time-windowed search for vertical motion on broadband seismograms
…/query?net=FR&cha=BHZ&starttime=2008-09-01&endtime=2009-01-01
*json listing of global repositories known to the fedcatalog (/datacenters endpoint)
…/datacenters?format=json
Detailed Descriptions of each Query Parameter
/query
| parameter | examples | discussion | default | type |
|---|---|---|---|---|
| Service options | ||||
| format | text | Specify output format. Accepted values are request (the default) and text, more details. |
request | string |
| targetservice | station | By default all known service endpoints are returned in the results. Specify station or dataselect to only return endpoints for one of those services. |
all | string |
| includeoverlaps | true | Control whether overlapping channel entries are included in the response (true or false). Overlapping entries will occur when the same data are available from multiple data centers. |
false | boolean |
| level | station | Specify level of detail (for an fdsnws-station service) using network, station, channel, or response. |
channel | string |
| datacenter | IRISDMC | Limit the results to metadata held at an FDSN data center of interest. Use data center codes available at the datacenters endpoint. Accepts wildcards, lists, and negation. | all | string |
| Channel constraints | ||||
| net[work] | IU | Select one or more network codes. Can be SEED codes or data center defined codes. Accepts wildcards and lists. | any | string |
| sta[tion] | ANMO | Select one or more SEED station codes. Accepts wildcards and lists. | any | string |
| loc[ation] | 00 | 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] | BH1 | Select one or more SEED channel codes. Accepts wildcards and lists. | any | string |
| Time constraints | ||||
| start[time] | 2001-12-31 | Limit to metadata listed on or after the specified start time. | any | day/time |
| end[time] | 2012-12-31 | Limit to metadata listed on or before the specified end time. | any | day/time |
| startbefore | 2001-12-31 | Limit to metadata epochs listed before specified time. Applied to channel epochs. | any | day/time |
| startafter | 2005-12-31 | Limit to metadata epochs listed after specified time. Applied to channel epochs. | any | day/time |
| endbefore | 2005-12-31 | Limit to metadata epochs ending before specified time. Applied to channel epochs. | any | day/time |
| endafter | 2005-12-31 | Limit to metadata epochs ending after specified time. Applied to channel epochs. | any | day/time |
| Rectangular geographic constraints | ||||
| minlat[itude] | 34.5 | Specify the southern boundary. | -90° | degrees |
| maxlat[itude] | 36.0 | Specify the northern boundary. | 90° | degrees |
| minlon[gitude] | -108.0 | Specify the western boundary. | -180° | degrees |
| maxlon[gitude] | -105.0 | Specify the eastern boundary. | 180° | degrees |
| Radial geographic constraints | ||||
| lat[itude] | 32.0 | Specify the central latitude point. | degrees | |
| lon[gitude] | -106.5 | Specify the central longitude point. | degrees | |
| maxradius | 10 | Specify maximum distance from the geographic point defined by latitude and longitude. |
N/A | degrees |
| minradius | 5 | Specify minimum distance from the geographic point defined by latitude and longitude. |
0 | degrees |
| Waveform options these are passive options, passed through in the response but otherwise unused | ||||
| quality | B | Select data based on miniSEED data quality indicator. D, R, Q, M, B. M and B (default) are treated the same and indicate best available. If M or B are selected, the output data records will be stamped with an M. |
B | quality |
| minimumlength | 0.0 | Limit results to continuous data segments of a minimum length specified in seconds. | 0.0 | Float |
| longestonly | false | Limit results to the longest continuous segment per channel. | false | boolean |
| Other Options these are passive options, passed through in the response but otherwise unused | ||||
| includerestricted | true | Specify whether results should include information relating to restricted channels. | true | boolean |
| includeavailability | true | Specify if results should include information about time series data availability at the channel level. | false | boolean |
| updatedafter | 2012-01-01 | Limit to metadata updated after specified UTC date; updates are data center specific. | any | day/time |
| matchtimeseries | true | Retrieve only metadata that is likely to match available time series data | false | boolean |
| 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.
/datacenters
| parameter | examples | discussion | default | type |
|---|---|---|---|---|
| Service options | ||||
| format | text | Specify output format. Accepted values are json (the default), html, and text, more details. |
json | 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
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.
