NSF SAGE Facility IRISWS timeseries Web Service Documentation

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

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 separators1)
demean true Remove mean value from data. true or false (default false).
scale 2.0 Scale data samples by specified factor2. When scale=AUTO scales by the stage-zero gain3
divscale 2.0 Scale data samples by the inverse of the specified factor2
correct true Apply instrument correction to convert to earth units. true or false. Uses either deconvolution3,4 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 separators1 )
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 separators1 )
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 to5. 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
miniseedFDSN miniSEED format
plot — A simple plot of the timeseries
sac.zipSAC Zipped binary traces
sacaSACASCII format [deprecated]
sacbbSAC – binary big-endian format [deprecated]
sacblSAC – binary little-endian format [deprecated]

Notes:

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

2 Cannot specify both scale and divscale.

3 Cannot specify both correct and scale=AUTO

4 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

5 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 nobody@iris.edu 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:
data-help@earthscope.org
We will address your issue as soon as possible.

IRISWS timeseries web service