IRIS DMC IRISWS availability Web Service Documentation

Description

The irisws-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] [sort-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>] 
sort-options       :: [rowlimit=<number>] [orderby=<nslc_time_quality_samplerate|timespancount|timespancount_desc|latestupdate|latestupdate_desc>]
format-options     :: [format=<text|geocsv|json|sync|request>] [show=<latestupdate,restriction,timespancount>]
misc-options       :: [includerestricted=<true|false>]
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>] [includerestricted=<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 values discussion default type
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 any quality
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 false true/false
mergesamplerate true If true, timespans from data with differing sample rates are grouped together false true/false
Other Options
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, sync 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 fdsnws-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:
nslc_time_quality_samplerate network, station, location, channel, time-range, quality, sample-rate (default)
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
rowlimit integer Limits output to this many rows. 0 or negative means unlimited.
Show Option
show comma separated list (example show=timespancount,restriction)
latestupdate display when the data was most recently updated
timespancount display number of timespans
restriction display restriction status: OPEN, RESTRICTED, PARTIAL

The /query method accepts these additional parameters:

Merge options
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

Page built 18:06:47 | v.793f85ec