NSF SAGE: IRISWS: Timeseries: Docs: v. 1

Service interface URL builder Help Revisions

Description

The irisws-timeseries service provides access to individual channels of time series data for a specified time range. Requested segments may be up to 30 days in length and optional signal processing may be applied to return data. The time series may be returned in a variety of formats.

Output format options:

miniSEED
SAC zip (binary little endian)
~~SAC Alpha~~ (ASCII) [deprecated]
~~SAC binary~~ (big & little endian) [deprecated]
Audio (WAV format)
PNG Plot
ASCII (data column)
ASCII (data column, time column)
GEOCSV (data column)
GEOCSV (data column, time column)

Signal processing options (operations are performed in the order specified):

high, low and band-pass filter
remove mean value
scaling by constant value
deconvolution of instrument response (with frequency limits and unit conversion)
differentiation and integration
decimation to lower sample rates

Below is a full list of service parameters and their usage.

Query Usage

/query? (channel-options) (date-range-options) (filter-options) [plot-options] [audio-options] (output-options)

where:

channel-options      ::  (net=<network> & sta=<station> & loc=<location> & cha=<channel>)
date-range-options   ::  (starttime=<time>) & ([endtime=<time>] | [duration=<seconds>])
filter-options       ::  [taper=WIDTH,TYPE] [envelope] [lpfilter=FREQ] [hpfilter=FREQ]
                         [bpfilter=HIFREQ-LOFREQ] [demean=<true|false>] [diff=<true|false>] [int=<true|false>] [scale=number|AUTO] 
                         [divscale=number] [correct=<true|false>] [freqlimits=F1-F2-F3-F4] 
                         [autolimits=lowerdBdown-upperdBdown] 
                         [units=<DEF|DIS|VEL|ACC>] [decimate=SAMPLERATE]
plot-options         ::  [antialiasplot=<true|false>]
audio-options        ::  [audiocompress=<true|false>] [audiosamplerate=<playback-rate-hz>]
output-options       ::  (output=output-options       
                     ::  (format=<miniseed|sac.zip|saca|sacbb|sacbl|plot|ascii|ascii1|ascii2|geocsv|geocsv.tspair|geocsv.slist|audio>)

(..) required
[..] optional

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

Sample Queries

http://service.iris.edu/irisws/timeseries/1/query?net=IU&sta=ANMO&loc=00&cha=BHZ&starttime=2005-01-01T00:00:00&endtime=2005-01-02T00:00:00&output=plot

Detailed Descriptions of each Query Parameter

parameters	examples	discussion
Channel Options (required) The four SCNL parameters (Station – Channel – Network – Location) are used to determine the channel of interest, and are all required. Wildcards are not accepted.
net[work]	IU	Seismic network name
sta[tion]	ANMO	Station name
loc[ation]	00	Location code. Use `loc=--` for empty location codes
cha[nnel]	BHZ	Channel Code
Date-Range Options (required) Time ranges must be defined by specifying a start time with either an end time or a duration in seconds. For example, the following two time specifications are valid, and are equivalent. Examples `...starttime=2005-02-23T12:00:00&endtime=2005-02-23T12:05:00...` `...starttime=2005-02-23T12:00:00&duration=300...`
start[time]	2001-12-09T12:00:00	Start time
end[time]	2001-12-09T12:20:00	End time
dur[ation]	30	Duration of requested data, in seconds
Time Series Processing Options The following parameters act as filters upon the timeseries. Parameter order matters because each filter operation is performed in the order given. Examples `...demean&lpfilter=2.0` — will demean and then apply a low-pass filter `...lpfilter=2.0&demean` — will apply a low-pass filter, and then demean
taper	0.25 0.33,HANNING 0.5,COSINE 0.5,HAMMING	Apply a time domain symmetric tapering function to the timeseries data. The width is specified as a fraction of the trace length from 0 to 0.5. The width may be optionally followed by window type as WIDTH,TYPE. Supported types: HANNING (default), HAMMING, COSINE
envelope	true	Calculate the envelope of the time series. This calculation uses a Hilbert transform approximated by a time domain filter
lp[filter]	1.0	Low-pass filter the time-series using an IIR 4th order filter, using this value (in Hertz) as the cutoff
hp[filter]	3.0	High-pass filter the time-series using an IIR 4th order filter, using this value (in Hertz) as the cutoff
bp[filter]	0.1-1.0	Band pass frequencies, in Hz. (See NOTE on variable separators¹)
demean	true	Remove mean value from data. true or false (default false).
scale	2.0	Scale data samples by specified factor². When `scale=AUTO` scales by the stage-zero gain³
divscale	2.0	Scale data samples by the inverse of the specified factor²
correct	true	Apply instrument correction to convert to earth units. true or false. Uses either deconvolution³,⁴ or polynomial response correction. true or false (default false)
freqlimits	0.0033–0.004–0.05–0.06	Specify an envelope for a spectrum taper for deconvolution. Frequencies are specified in Hertz. This cosine taper scales the spectrum from 0 to 1 between f1 and f2 and from 1 to 0 between f3 and f4. Can only be used with the `correct` option. Cannot be used in combination with the `autolimits` option. (See NOTE on variable separators¹ )
autolimits	3.0,3.0	Automatically determine frequency limits for deconvolution. A pass band is determined for all frequencies with the lower and upper corner cutoffs defined in terms of dB down from the maximum amplitude. This algorithm is designed to work with flat responses, i.e. a response in velocity for an instrument which is flat to velocity. Other combinations will likely result in unsatisfactory results. Cannot be used in combination with the `freqlimits` option. See further description for autolimits (See NOTE on variable separators¹ )
units	VEL	Specify output units. Can be DIS, VEL, ACC or DEF, where DEF results in no unit conversion `UNITS` can only be used with `correct`
diff	true	Differentiate using 2 point (uncentered) method. true or false (default false)
int	false	Integrate using trapezoidal (midpoint) method. true or false (default false)
deci[mate]	2.0	Sample-rate to decimate to⁵. See Help for more details. A linear-phase, anti-alias filter is applied during decimation.
Plot Options
antialias[plot]	true	If true, the created image will have anti-aliasing used. Can only be specified with the `output=plot` option
width	1000	Width of the output plot (pixels). Can only be specified with the `output=plot` option
height	70	Height of the output plot (pixels). Can only be specified with the `output=plot` option
Audio Options
audiosamplerate	30000	The sample rate of the output wav file in Hz. Defaults to 16000. Must be an integer. Can only be specified with the `output=audio` option
audiocompress	true	Apply dynamic range compression to waveform data. This makes more of the signal audible. Can only be specified with the `output=audio` option
Format Options
format ~~output~~ [deprecated]	miniseed	Required `ascii1` — ascii data format, 1 column (values) `ascii2` — ascii data format, 2 columns (time, value) `ascii` — Same as ascii2 `geocsv`, `geocsv.tspair` — ascii geocsv data format, 2 column (time, values) `geocsv.slist` — ascii geocsv data format, 1 columns (value) `audio` — audio WAV file `miniseed` — FDSN miniSEED format `plot` — A simple plot of the timeseries `sac.zip` — SAC Zipped binary traces ~~saca~~ — SAC – ASCII format [deprecated] ~~sacbb~~ — SAC – binary big-endian format [deprecated] ~~sacbl~~ — SAC – binary little-endian format [deprecated]

Notes:

¹ Frequency numbers maybe separated by - / , and ; . For example 0.001-0.01

² Cannot specify both scale and divscale.

³ Cannot specify both correct and scale=AUTO

⁴ Correction on > 10^7 samples will result in an error. At a sample rate of 20 Hz, 10^7 samples is approximately 5.8 days

⁵ The output sample rate will only exactly match the selected decimation rate if the ratio of original to final rate is factorable by 2,3,5 and 7. Otherwise, the closest factorable rate will be chosen.

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

Restricted Data Access

For access to restricted data, requests should be sent to: service/irisws/timeseries/1/queryauth

Requests sent to this URL are authenticated via digest access authentication in order to establish the caller's credentials. For anonymous access, the user [email protected] and password anonymous may be used. This credential has identical data access permission as the regular submit path's: service/irisws/timeseries/1/query

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.

IRISWS timeseries web service

NSF SAGE Facility IRISWS timeseries Web Service Documentation