NSF SAGE Facility IRISWS fedcatalog Web Service Documentation

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:

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

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.

IRISWS fedcatalog web service