Description
The timeseriesplot service returns a graphical representation of time series data at the channel level for a specific time range.
Output format options:
- PNG
- JPEG
The service request offers several options:
- single-series or “helicorder” style plots
- a current-day indicator making it easy to obtain daily results
- scaling of the plot to adjust the overall look
- plot in raw instrument output or convert to earth units
- monochrome or color mode
Below is a full list of service parameters and their usage.
Query Usage
/query? (channel-options) (date-range-options) [plot-options] [output-options]
where:
channel-options :: (net=<network> & sta=<station> & loc=<location> & cha=<channel>) date-range-options :: (starttime=<time>|duration) & (endtime=<time>|duration) plot-options :: [showtitle=<TRUE|false>] [showscale=<TRUE|false>] [monochrome=<true|FALSE>] plot-options :: [helicordermode=<true|FALSE>] [segmentsperhour=<1-6>] plot-options :: [earthunits=<TRUE|false>] [unitscale=<n>=0>] [demean=<true|FALSE>] plot-options :: [width=<400-2000>] [height=<200-2000>] filter-options :: [lp=FREQ] [hp=FREQ] [bp=LOFREQ-HIFREQ] output-option :: [format=<png|jpeg>]
(..) required [..] optional default values in all caps, e.g., TRUE
Query parameters are joined by ampersands &, without blank space (see the sample queries).
Sample Queries
- http://service.iris.edu/irisws/timeseriesplot/1/query?net=IU&sta=ANMO&loc=00&cha=LHZ&start=2004-12-26T00:00:00&end=2004-12-26T13:01:00
- http://service.iris.edu/irisws/timeseriesplot/1/query?net=IU&sta=ANMO&loc=00&cha=LHZ&start=currentutcday&end=86400
Detailed Descriptions of each Query Parameter
parameter | examples | discussion | default | type |
---|---|---|---|---|
Channel Options (required) The four SNCL parameters (Station – Network – Channel – Location) are used to determine the channel of interest, and are all required. Wildcards are not accepted. |
||||
net[work] | IU | Seismic network name | N/A | string |
sta[tion] | ANMO | Station name | N/A | string |
loc[ation] | 00 | Location code. Use loc=-- for empty location codes |
N/A | string |
cha[nnel] | BHZ | Channel Code | N/A | string |
Date-Range Options (required, can be expressed as calendar dates, duration (seconds), or the key word: ‘currentutcday’) Time ranges can be defined by specifying a start time and an end time. Example ...starttime=2005-02-23T12:00:00&endtime=2005-02-23T12:05:00... |
||||
start[time] | 2001-12-09T12:00:00 | Start time | N/A | day/time |
end[time] | 2001-12-09T12:20:00 | End time | N/A | day/time |
Alternatively, time ranges can be defined by a combination of a calendar date and a duration in units of seconds. The following example specifies a calendar date as the starttime plus a 24-hour duration specified in the endtime parameter: Example ...starttime=2005-02-23T12:00:00&endtime=86400... |
||||
start[time] | 2001-12-09T12:00:00 | Start time expressed as a calendar date | N/A | day/time |
end[time] | 86400 | End time expressed as a duration (seconds) | N/A | integer |
In addition, time ranges can be defined by a combination of the key word ‘currentutcday’ and a duration in units of seconds. The key word ‘currentutcday’ means exactly midnight of today’s date (UTC time). The following example specifies today’s midnight (UTC) as the starttime plus a 24-hour duration specified in the endtime parameter: Example ...starttime=currentutcday&endtime=86400... NOTE: the key word ‘currentutcday’ can also be used for the end[time] parameter indicating exactly midnight of today’s date. In this case the duration specified in the start[time] parameter specifies the duration prior to midnight (i.e., the previous day). |
||||
start[time] | currentutcday | today’s midnight (UTC) | N/A | string |
end[time] | 86400 | End time expressed as a duration (seconds) | N/A | integer |
Plot Options | ||||
showtitle | true | If true, the created image will include a title across the top showing the Channel and Date-Range information |
true | boolean |
showscale | true | If true, a scale will be shown on the right-side axis. This is independent of the earthunits option |
true | boolean |
monochrome | false | If false, the created image will be drawn in color. True creates a grayscale image. | false | boolean |
helicordermode | true | If true the result is in “helicorder” style in which the timeseries data is shown in stacked time segments. See the segmentsperhour option. If false the plot is said to be in “single-series” mode. |
false | boolean |
segmentsperhour | 3 | Integer ranging from 1 to 6. Indicates the number of segments for each hour of timeseries data when in helicorder mode. | 1 | integer |
earthunits | true | If true, the values are scaled to the units of the instrument. Should metadata for the channel be unavailable, the data will be plotted in raw units. | true | boolean |
unitscale | 0.001 | Number greater than or equal to zero. Provides absolute scale factor for consistency in day-to-day plotting. Scales plot to X/100pixels. Value of zero (default) indicates no absolute scaling. | 0 | numeric |
demean | true | If true, subtract the sample mean from each value. | false | boolean |
width | 500 | Width of the output plot (pixels). The range is 400 to 2000. Note that the default is 1200 if in single-series mode and 900 in helicorder mode. | 1200 or 900 | integer |
height | 400 | Height of the output plot (pixels). The range is 200 to 2000. Note that the default is 400 if in single-series mode and 1000 in helicorder mode. | 400 or 1000 | integer |
lp | 1.0 | Apply a low-pass filter cutoff (Hz) using a Butterworth 4th order filter. | N/A | float |
hp | 0.1 | Apply a high-pass filter cutoff (Hz) using a Butterworth 4th order filter. | N/A | float |
bp | 0.1,1.0 | Apply a band-pass filter range (Hz) using a Butterworth 4th order filter. Define the frequency band with lower and upper values separated by a comma, semi-colon, dash, or forward-slash. | N/A | float |
Output Option | ||||
format | jpeg | The desired image type of the plot. | png | string |
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/timeseriesplot/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/timeseriesplot/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.