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).

/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).

/extent POST Usage

Alternatively, instead of providing parameter-value pairs in the URL, a file containing a selection list can be POSTed to this service.

nodata=404
Network Station Location Channel
Network Station Location Channel
...

/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=404]

Query parameters are joined by ampersands ”&”, without blank space (see the sample queries).

/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. 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.

nodata=404
Network Station Location Channel StartTime EndTime
Network Station Location Channel StartTime EndTime
...

Wildcards are acceptable for Network, Station, Location, and Channel. Click here for time format details.

Sample Queries

Extent information for all network IU, station ANMO channels in text format (default)
http://service.iris.edu/irisws/availability/1/extent?network=IU&station=ANMO

Same query as previous in JSON format
http://service.iris.edu/irisws/availability/1/extent?network=IU&station=ANMO&format=json

Extent information for all network IU, sorted by number of time-spans descending, limited to 100 rows (default)
http://service.iris.edu/irisws/availability/1/extent?network=IU&orderby=timespancount_desc&rowlimit=100

Extent information for all network IU, sorted by update-date, limited to 100 rows (default)
http://service.iris.edu/irisws/availability/1/extent?network=IU&orderby=latestupdate&rowlimit=100

Data from network IU, station ANMO, channel BHZ for the 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

Same query as above, but with qualities merged (default behavior)
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=true

One year of timespans for network IU, station ANMO, location 00 and channel BHZ show all qualities.
http://service.iris.edu/irisws/availability/1/query?network=IU&station=ANMO&channel=BHZ&location=00&start=2010-02-23T00:00:00&end=2011-02-23T00:00:00&mergequality=false

Same as previous with qualities merged (default behavior).
http://service.iris.edu/irisws/availability/1/query?network=IU&station=ANMO&channel=BHZ&location=00&start=2010-02-23T00:00:00&end=2011-02-23T00:00:00&mergequality=true

Same as previous with overlaps merged.
http://service.iris.edu/irisws/availability/1/query?network=IU&station=ANMO&channel=BHZ&location=00&start=2010-02-23T00:00:00&end=2011-02-23T00:00:00&mergequality=true&mergeoverlap=true

Data from network IU, station ANMO, channel BHZ for the given time interval show latest update times for timespans
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&showlastupdate=true

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

VERSION

HOST

BASEURL

IRISWS availability web service