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 conversionUNITS 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 |
miniseed | Requiredascii1 — ascii data format, 1 column (values)ascii2 — ascii data format, 2 columns (time, value)ascii — Same as ascii2geocsv , geocsv.tspair — ascii geocsv data format, 2 column (time, values)geocsv.slist — ascii geocsv data format, 1 columns (value)audio — audio WAV fileminiseed — FDSN miniSEED formatplot — A simple plot of the timeseriessac.zip — SAC Zipped binary traces |
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:
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.