IRIS DMC IRISWS availability Web Service Documentation

Description

The irisws-availability web service returns detailed time span information of timeseries data available in 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).

/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] [sort-options] [format-options] [nodata=404] 

where

channel-options    :: [net=<network>] [sta=<station>] [loc=<location>] [cha=<channel>] [quality=<quality>]
sort-options       :: [rowlimit=<number>] [orderby=<nslc_time_quality_samplerate|timespancount|timespancount_desc|latestupdate|latestupdate_desc>]
format-options     :: [format=<text|geocsv|json|sync>]
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] [misc-options] [format-options] [nodata=404] 

where

channel-options    ::  [net=<network>] [sta=<station>] [loc=<location>] [cha=<channel>] [quality=<quality>]
time-constraints   ::  [starttime=<date>] [endtime=<date>]
merge-options      ::  [mergequality=<true|false>] [mergesamplerate=<true|false>] [mergeoverlap=<true|false>] [mergetolerance=<seconds>]
misc-options       ::  [excludetoolarge=<true|false>] [showlastupdate=<true|false>]
format-options     ::  [format=<text|geocsv|sync|json>
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 IU, station ANMO channels in text format
http://service.iris.edu/irisws/availability/1/extent?network=IU&station=ANMO

Available Data from network IU, station ANMO, channel BHZ for a given time interval
http://service.iris.edu/irisws/availability/1/query?network=IU&station=ANMO&channel=BHZ&start=2010-02-23T00:00:00&end=2010-03-23T00:00:00&mergequality=false

Detailed Descriptions of each Query Parameter

Common Parameters

/extent and /query accept these common parameters.

parameter examples discussion default type
format json Specify output format. Accepted values are text (the default), geocsv, json and sync. The text format is meant to be human readable.
Channel contraints
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
quality R Select based on SEED quality codes D, M, Q, R. Wildcard * as well as a comma selected list are accepted * quality
Other Options these are passive options, passed through in the response but otherwise unused
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:

parameter values discussion default
rowlimit integer Limits output to this many rows. 0 or negative means unlimited. unlimited
orderby How to sort rows. nslc_time_quality_samplerate
nslc_time_quality_samplerate network, station, location, channel, time-range, quality, sample-rate
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
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

The /query method accepts these additional parameters:

parameter examples discussion default type
Time constraints
start[time] 2015-10-18T00:00:00 Limit to timespans on or after the specified start time. any day/time
end[time] 2016-06-27T00:00:00 Limit to timespans before the specified end time. any day/time
Merge options
mergequality true If true, timespans from data with differing qualities are grouped together true true/false
mergesamplerate true If true, timespans from data with differing sample rates are grouped together false true/false
mergeoverlap true If true, overlapping timespans are merged together. false true/false
mergetolerance 86400.0 (1 day) Can only be used with mergeoverlap=true. If true, timespans which are separated by gaps smaller than or equal to the given value are merged together. To have an effect, the mergetolerance value must be larger than 1.5 times the sample period Seconds, Float
Misc options
showlastupdate true If true, the latest dates at which data for timespans were loaded into the archive are displayed. false true/false
excludetoolarge true A small number of channels (less than 200) are too fragmented for the service to process. By default, the service silently ignores these channels. If false, the service reports a 413 error (request too large) if any of these channels are selected true true/false

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

IRISWS availability web service