Manuals: IRIS-WS

Jump to

Introduction

This tutorial illustrates how to access station, event, and time series (waveform) data from IRIS using the Java Web Service Library.

Example code is included with the .zip file download

Work flow overview

Each example, and the recommended usage pattern, uses the Java Web Service Library in the following manner:

  • Initialize the services, using the ServiceUtil class.
  • Specify the data of interest, using one the service-specific criteria classes.
  • Fetch the data from the service, using your initialized service.
  • Process the returned java objects.

Quick jump to examples

  • Trace tutorial, a simple example of requesting Trace data (time series & related metadata)
  • Station tutorial, a simple example of requesting and printing station metadata
  • Event tutorial, a simple example of requesting and printing event (earthquake) parameters
  • Waveform tutorial, a simple example of requesting time series (waveforms)
  • Resp tutorial, a simple example of printing resp format (from stationxml).

Service class overview

Each service will be initialized through a ServiceUtil class, which handles reading of service-related parameters and avoids creation of unnecessary copies of Service classes.

The Trace class combines the functionality multiple services in
order to return a seismic trace containing data along its associated metadata

Trace Classes

TraceData uses the StationService, WaveformService, and SacpzService classes to retrieve information. It may use either StationCriteria or channel and time parameters to refine the search. Results are returned as a list of Trace objects, which are SAC-like representations of the waveform and channel metadata. Additionally, responses can be obtained, in SAC poles and zeros format.

There are four fundamental data types (classes), each corresponding to a specific IRIS web service. These are:

StationService is used to connect to the fdsn-station webservice, using StationCriteria to refine the search. Results are returned as either a list of Network objects (representing content from StationXML) or a Java stream of returned Station XML.

EventService is used to connect to the fdsn-station webservice, using EventCriteria to refine the search. Results are returned as either an Event (representing content from QuakeML) or as a Java stream of returned QuakeML.

WaveformService is used to connect to the ws-bulkdataselect webservice, using WaveformCriteria to refine the search. Results are returned in objects of the Timeseries class (one per continuous trace segment) or as a Java stream of returned miniSEED records.

SacpzService is used to connect to the ws-sacpz webservice, using SacpzCriteria to refine the search.

Working Tutorial: The Bare Bones Outline for all examples

Import the appropriate java classes

These classes include all the station, waveform, and event-related classes, as well as error-handling classes, and date classes. Not all these classes would be needed for each application, but the tutorial will make use of all of them. For an accurate list of imports required with each example, check out the individual example .java files that are available in the .zip download 

// Import the error handling classes
import edu.iris.dmc.criteria.CriteriaException;  
// error handling
//<i>... more here...
//
// ServiceUtil is where we obtain all the "hooks" to the web services.
import edu.iris.dmc.service.ServiceUtil;
//
// Import the classes specific to the STATION example
// Import the classes specific to the WAVEFORM example
// Import the classes specific to the EVENT example
// Import other Java classes>
//
public class MyWSTutorialClass {
  public static void main(String[] args) {
     // get access to the services
     // specify criteria
     // fetch data
     // process data
  }
}

Working Tutorial: Importing and printing Trace metadata

Download the complete .java file for this example.

Initialize the services

The following example grabs trace data for a few stations in a network. This code, and all of this example’s following code, would go within
the main function of the bare bones outline.

TraceData traceFetcher = TraceData();
traceFetcher.setAppName("Tutorials");</pre>

Specify the criteria and Fetch the results

This example fetches traces for a few stations in the IU network.

// define the dates of interest
DateFormat dfm = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSS");
dfm.setTimeZone(TimeZone.getTimeZone("GMT"));
//
Date startDate = dfm.parse("2006-09-11T00:00:00.000");
Date endDate = dfm.parse("2006-09-11T00:01:45.000");
Boolean includePZ = true;
Trace traces []=null;  
// Traces are unique in that you could provide a station criteria object (as in the station example) or
// you can specify simple criteria directly in the call.</span>
traces = traceFetcher.fetchTraces("IU", "AN*,B*","00","BHZ",
         startDate, endDate, 'B', includePZ);

For additional detail about specifying station search criteria, consult the StationCriteria class within the Java Doc.

Display the results

The traces that are returned contain information akin to that found in SAC files. Let’s loop through it to see what was returned.

//loop through all the channels to display the details
for (Trace trace : traces) {
   System.out.printf("Found %2s-%5s (%2s)  from %15s to %15s\n",
      trace.getNetwork(),trace.getStation(),trace.getChannel(),
      trace.getStartTime().toString(), trace.getEndTime().toString());
   System.out.printf("  This trace has %d samples, at %7.2f samples per second\n",
	   trace.getSampleCount(), trace.getSampleRate());
   System.out.printf("  This channel is located at: %8.4f lat, %8.4f lon, elev %.0f m\n\n",
      trace.getLatitude(), trace.getLongitude(), trace.getElevation());
}

Expected Output from the TRACE tutorial 

Found IU- ANMO (BHZ)  from 2006-09-10 17:00:00.0358 to 2006-09-10 17:01:44.9858
  This trace has 2100 samples, at   20.00 samples per second
  This channel is located at:  34.9460 lat, -106.4571 lon, elev 1671 m

Found IU- ANTO (BHZ)  from 2006-09-10 17:00:00.0108 to 2006-09-10 17:01:44.96084
  This trace has 2100 samples, at   20.00 samples per second
  This channel is located at:  39.8680 lat,  32.7934 lon, elev 895 m

Found IU- BBSR (BHZ)  from 2006-09-10 17:00:00.0346 to 2006-09-10 17:01:44.984678
  This trace has 2100 samples, at   20.00 samples per second
  This channel is located at:  32.3713 lat, -64.6963 lon, elev -1 m

Found IU- BILL (BHZ)  from 2006-09-10 17:00:00.0485 to 2006-09-10 17:01:44.9985
  This trace has 2100 samples, at   20.00 samples per second
  This channel is located at:  68.0653 lat, 166.4531 lon, elev 320 m

Download the complete .java file for this example.

Working Tutorial: Importing and printing Station metadata

Initialize the services

The following example uses the ServiceUtil class to initialize (get an instance of) the StationService. This code, and all of this example’s following code, would go within the main function of the bare bones outline.

ServiceUtil serviceUtil = ServiceUtil.getInstance();
serviceUtil.setAppName("Tutorials");
StationService stationService = serviceUtil.getStationService();

This example fetches the metadata from station ANMO in the IU network, valid from 1993 through 2001.

// define the dates of interest</span>
DateFormat dfm = new SimpleDateFormat("yyyy-MM-dd");
dfm.setTimeZone(TimeZone.getTimeZone("GMT"));
//
Date startDate = dfm.parse("1993-01-01");
Date endDate = dfm.parse("2002-01-01");
//
// specify the search criteria</span>
StationCriteria stationCriteria = new StationCriteria();
stationCriteria = stationCriteria.addNetwork("IU").addStation("ANMO").
setStartAfter(startdate).setEndBefore(enddate);

Criteria names are generally based upon the parameters that are used within each webservice. Since each webservice has a different set of search parameters, each webservice will have its own criteria class (e.g. StationService accepts StationCriteria as input, while EventService accepts EventCriteria).

Empty Criteria objects

A criteria object with no specified parameters will result in a search with no constraints, and may result in vast amounts of information being transferred.

Wildcards

Certain parameters support wildcards (* or ?) or lists (station1, station2, …). StationCriteria parameters that accept these include addNetwork, addStation, addLocation, and addChannel.

Parameter Naming Conventions

  • addParametername
    can be used to grow a list of criteria, with each subsequent call adding another possibility. For example, to return station results for both the IU and AV networks, you might use the following stationCriteria:
sc = stationCriteria.addNetwork("IU").addNetwork("AV");

which is equivalent to…

sc = stationCriteria.addNetwork("IU"); sc = sc.addNetwork("AV");
  • setSomething

will change the value of that particular criteria. Subsequent calls will replace the value. For example:

sc = stationCriteria.setSomething(whatever);

Additional calls to setSomething would merely replace this choice.

For additional detail about specifying station search criteria, consult the StationCriteria class within the Java Doc.

Fetch the results

Now we use the stationcriteria to fetch a list of Network objects from the station webservice. Each network object may contain the detail for stations within it. We’ll also specify the level of detail to fetch by using the java enum OutputLevel.

// fetch the data from the service, using the stationCriteria
// The fdsn-station service can be queried for different levels of detail.
// We're asking for CHANNEL detail, but could have chosen STATION or NETWORK, too.
//
List<Network> ls = stationService.fetch(stationCriteria, OutputLevel.CHANNEL);

Display the results

The StationXML is nested according to network, station and channel. Therefore, we will loop through this hierarchy to display the results.

// loop through all the channels to display the details
		for (Network n : ls) {
			System.out.printf("Network : %s with %d stations\n", n.getCode(),
					n.getSelectedNumberStations());
			// each network may have multiple stations
			for (Station s : n.getStations()) {
				System.out.printf("\tStation : %s with %d channels\n",
						s.getCode(), s.getChannels().size());
				for (Channel c : s.getChannels()) {
					// Finally! Print the detail
					System.out.printf("\t\tChannel: %s on: %s   off:%s\n",
							c.getCode(), c.getStartDate(), c.getEndDate());
				}
			}
		}

Expected Output from the Station tutorial 

Network : IU with 1 stations
	Station : ANMO with 172 channels
		Channel: LDO on: 2000-08-16T14:00:00   off:2000-10-19T16:00:00
		Channel: BH1 on: 2000-07-19T14:00:00   off:2000-10-19T16:00:00
		Channel: BH2 on: 2000-07-19T14:00:00   off:2000-10-19T16:00:00
		Channel: BHZ on: 2000-07-19T14:00:00   off:2000-10-19T16:00:00
		Channel: HH1 on: 2000-07-19T14:00:00   off:2000-10-19T16:00:00
		Channel: HH2 on: 2000-07-19T14:00:00   off:2000-10-19T16:00:00
          ...<i><b>continued</b></i>

Working Tutorial: Importing and displaying Event information

In this example, we’ll flesh out the The Bare Bones Outline’s main function in order to fetch and display some event information.

Initialize the services 

ServiceUtil serviceUtil = ServiceUtil.getInstance();
serviceUtil.setAppName("Tutorials");
EventService eventService = serviceUtil.getEventService();

Specify the Criteria

In this example, we’ll fetch all events that are in the IRIS database that have occurred between 44.8 and 45.0 degrees Latitude and have a mangnitude of 5.0 or greater.

// we aren't concerned with a date range in this example,
// but we COULD have specified a range as seen in the previous examples</span>
EventCriteria criteria = new EventCriteria();
criteria.setMaximumLatitude(45.0);
criteria.setMinimumLatitude(44.8);
criteria.setMinimumMagnitude(5.0);

A great many selection criteria are available, and reflect the parameters seen in the fdsn-event service. For more thorough listing of available parameters, consult the EventCriteria class within the Java Doc.

Fetch the results

Once again, the Service’s fetch routine is used.

// get a list of Event objects   
List<Event> events = eventService.fetch(criteria);

Display the results 

for (Event e : events) {
   System.out.println("Event: " + e.getType() + " " + e.getFlinnEngdahlRegionName());
   System.out.println("\t"+e.getPreferredOrigin());
   for(Magnitude magnitude:e.getMagnitudes()){
      System.out.printf("\tMag: %3.1f %s\n",
         magnitude.getValue(),
         magnitude.getType());
      }
   }

Output from the Event tutorial

Because the criteria for this search did not specify a date range, the output may be preceded by additional events.

Event: earthquake  EAST OF KURIL ISLANDS
    Origin [publicId=smi:www.iris.edu/ws/event/query?originId=7636191, latitude=44.817, longitude=150.086, depth=40.2, time=Fri Feb 18 20:20:30 PST 2011]
    Mag: 5.4 MB
Event: earthquake  KURIL ISLANDS
    Origin [publicId=smi:www.iris.edu/ws/event/query?originId=5194528, latitude=44.857, longitude=147.973, depth=97.9, time=Sat Jul 25 11:32:22 PDT 2009]
    Mag: 5.1 MB
    Mag: 5.0 MW
Event: earthquake   KURIL ISLANDS
    Origin [publicId=smi:www.iris.edu/ws/event/query?originId=5192839, latitude=44.978, longitude=148.151, depth=93.9, time=Wed Jun 10 15:54:55 PDT 2009]
    Mag: 5.0 MB
Event: earthquake  EAST OF KURIL ISLANDS
    ...<i><b>continued</b></i>

Working Tutorial: Importing and displaying Waveform information

In this example, we’ll flesh out the Bare Bones Outline’s main function in order to fetch and display some waveform information.

Initialize the services 

ServiceUtil serviceUtil = ServiceUtil.getInstance();
serviceUtil.setAppName("Tutorials");
WaveformService waveformService = serviceUtil.getWaveformService();

Specify the Criteria

In this example, we take advantage of the WaveformCriteria’s helper function that allows us to specify (in one place) a network, station, channel, location, starttime, and endtime.

// We're specifying the BulkDataRequest equivalent of:
// IU ANMO 00 BHZ 2006-09-11T00:00:00 2006-09-11T00:01:00
// define the dates of interest
DateFormat dfm = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss");
dfm.setTimeZone(TimeZone.getTimeZone("GMT"));
Date startDate = dfm.parse("2006-09-11T00:00:00");
Date endDate = dfm.parse("2006-09-11T00:01:00");
WaveformCriteria criteria = new WaveformCriteria();
criteria.add("IU", "ANMO", "00", "BHZ", startDate, endDate);
// to request additional data, we coulld use more criteria.add(...) statements

Parameter limits and usage are dictated by the fdsn-dataselect service unless otherwise noted. Empty WaveformCriteria objects are not allowed. For additional detail about working with the waveform criteria webservice, consult the WaveformCriteria class within the Java Doc.

Fetch the results

Once again, the retrieval is straight forward. Simply call the service’s FETCH routine, providing it with the search criteria. The results will be returned in a list of Timeseries objects

// get a list of Timeseries objects
List<Timeseries> timeSeriesCollection = waveformService.fetch(criteria);

Converted SEED data is available in two classes

Requests convert the returned SEED data, such that it will be available in two classes Timeseries and Segment.

Timeseries
The Timeseries class organizes data into unique channels according to the SEED format nomenclature.
Segment
The Segment class is used to contain a contiguous segment of time series data, collections of Segments are associated with each Timeseries

Display the results

Display all the location information as well as the sample count and start-time of the retrieved segments

for(Timeseries timeseries:timeSeriesCollection){
   System.out.println(timeseries.getNetworkCode() + "-" +
   timeseries.getStationCode() + " (" + timeseries.getChannelCode() + "), loc:" +
      timeseries.getLocation());
      for(Segment segment:timeseries.getSegments()){
         System.out.printf("Segment:\n");
         System.out.printf("  Start: %s", segment.getStartTime());
         System.out.printf("  %d samples exist in this segment\n",
            segment.getSampleCount());         
   }
}

Output from the WAVEFORM tutorial 

IU-ANMO (BHZ), loc:00
Segment:
  Start: 2006-09-10 17:00:00.0358  1200 samples exist in this segment
IU-ANMO (BHZ), loc:10
Segment:
  Start: 2006-09-10 17:00:00.0233  2400 samples exist in this segment

Working Tutorial: Importing stations and printing in Resp format

Initialize the services

The following example uses the ServiceUtil class to initialize (get an instance of) the StationService. This code, and all of this example’s following code, would go within the main function of the bare bones outline.

ServiceUtil serviceUtil = ServiceUtil.getInstance();
serviceUtil.setAppName("Tutorials");
StationService stationService = serviceUtil.getStationService();

This example fetches the metadata from station ANMO in the IU network, valid from 1993 through 2001.

// define the dates of interest</span>
DateFormat dfm = new SimpleDateFormat("yyyy-MM-dd");
dfm.setTimeZone(TimeZone.getTimeZone("GMT"));
//
Date startDate = dfm.parse("1998-10-26");
Date endDate = dfm.parse("1998-10-27");
//
// specify the search criteria</span>
StationCriteria stationCriteria = new StationCriteria();
stationCriteria = stationCriteria.addNetwork("IU").addStation("ANMO").addLocation("00").
setStartAfter(startDate).setEndBefore(endDate);

Fetch the results 

// fetch the data from the service, using the stationCriteria
// The fdsn-station service can be queried for different levels of detail.
// We're asking for CHANNEL detail, but could have chosen STATION or NETWORK, too.
//
List<Network> ls = stationService.fetch(stationCriteria, OutputLevel.RESPONSE);


RespUtil.write(System.out, ls);

Output from the RESP tutorial 

B050F03     Station:     ANMO
B050F16     Network:     IU
B052F03     Location:    00
B052F04     Channel:     BHZ
B052F22     Start date:  1998,299,20:00:00
B052F23     End date:    2000,293,16:00:00
#
#                  +-----------------------------------+
#                  |    Response (Poles and Zeros)     |
#                  |        IU  ANMO   00  BHZ         |
#                  |     10/26/1998 to 10/19/2000      |
#                  +-----------------------------------+
#
B053F03     Transfer function type:                A
B053F04     Stage sequence number:                 1
B053F05     Response in units lookup:              M/S - Velocity in Meters Per Second
B053F06     Response out units lookup:             V - Volts
B053F07     A0 normalization factor:               +8.60830E+04
B053F08     Normalization frequency:               +2.00000E-02
B053F09     Number of zeroes:                      2
B053F14     Number of poles:                       5
#              Complex zeroes:
#              i  real          imag          real_error    imag_error
B053F10-13     0  +0.00000E+00  +0.00000E+00  +0.00000E+00  +0.00000E+00
B053F10-13     1  +0.00000E+00  +0.00000E+00  +0.00000E+00  +0.00000E+00
#              Complex poles:
#              i  real          imag          real_error    imag_error
B053F15-18     2  -5.94313E+01  +0.00000E+00  +0.00000E+00  +0.00000E+00
B053F15-18     3  -2.27121E+01  +2.71065E+01  +0.00000E+00  +0.00000E+00
B053F15-18     4  -2.27121E+01  -2.71065E+01  +0.00000E+00  +0.00000E+00
B053F15-18     5  -4.80040E-03  +0.00000E+00  +0.00000E+00  +0.00000E+00
B053F15-18     6  -7.31990E-02  +0.00000E+00  +0.00000E+00  +0.00000E+00
#
#                  +-----------------------------------+
#                  |      Channel Sensitivity/Gain     |
#                  |        IU  ANMO   00  BHZ         |
#                  |     10/26/1998 to 10/19/2000      |
#                  +-----------------------------------+
#
B058F03     Stage sequence number:                 1
B058F04     Sensitivity:                           +2.06168E+03
B058F05     Frequency of sensitivity:              +2.00000E-02
B058F06     Number of calibrations:                0
#
#                  +-----------------------------------+
#                  |      Response (Coefficients)      |
#                  |        IU  ANMO   00  BHZ         |
#                  |     10/26/1998 to 10/19/2000      |
#                  +-----------------------------------+
#
B054F03     Transfer function type:                D
B054F04     Stage sequence number:                 2
B054F05     Response in units lookup:              V - Volts
B054F06     Response out units lookup:             COUNTS - Digital Counts
B054F07     Number of numerators:                  0
B054F10     Number of denominators:                0
#
#                  +-----------------------------------+
#                  |            Decimation             |
#                  |        IU  ANMO   00  BHZ         |
#                  |     10/26/1998 to 10/19/2000      |
#                  +-----------------------------------+
#
B057F03     Stage sequence number:                  2
B057F04     Input sample rate (HZ):                 5.1200E+03
B057F05     Decimation factor:                      00001
B057F06     Decimation offset:                      00000
B057F07     Estimated delay (seconds):             +0.0000E+00
B057F08     Correction applied (seconds):          +0.0000E+00
#
#                  +-----------------------------------+
#                  |      Channel Sensitivity/Gain     |
#                  |        IU  ANMO   00  BHZ         |
#                  |     10/26/1998 to 10/19/2000      |
#                  +-----------------------------------+
#
B058F03     Stage sequence number:                 2
B058F04     Sensitivity:                           +4.19430E+05
B058F05     Frequency of sensitivity:              +0.00000E+00
B058F06     Number of calibrations:                0
#
#                  +-----------------------------------+
#                  |      Response (Coefficients)      |
#                  |        IU  ANMO   00  BHZ         |
#                  |     10/26/1998 to 10/19/2000      |
#                  +-----------------------------------+
#
B054F03     Transfer function type:                D
B054F04     Stage sequence number:                 3
B054F05     Response in units lookup:              COUNTS - Digital Counts
B054F06     Response out units lookup:             COUNTS - Digital Counts
B054F07     Number of numerators:                  64
B054F10     Number of denominators:                0
#              Numerator coefficients:
#              i  coefficient   error
B054F08-09     0  -1.09707E-03  +0.00000E+00
B054F08-09     1  -9.93327E-04  +0.00000E+00
B054F08-09     2  -1.33316E-03  +0.00000E+00
B054F08-09     3  -1.70526E-03  +0.00000E+00
B054F08-09     4  -2.05384E-03  +0.00000E+00
B054F08-09     5  -2.35065E-03  +0.00000E+00
B054F08-09     6  -2.57156E-03  +0.00000E+00
B054F08-09     7  -2.69373E-03  +0.00000E+00
B054F08-09     8  -2.69337E-03  +0.00000E+00
B054F08-09     9  -2.54709E-03  +0.00000E+00
B054F08-09    10  -2.23115E-03  +0.00000E+00
B054F08-09    11  -1.72301E-03  +0.00000E+00
B054F08-09    12  -9.99270E-04  +0.00000E+00
B054F08-09    13  -3.46562E-05  +0.00000E+00
B054F08-09    14  +1.21980E-03  +0.00000E+00
......

Related Content

These other pages were tagged similarly:

Categories

Tags

Web Service

Release date:     Modified date:

NSF SAGE Facility has been certified as a trustworthy data repository by the CoreTrustSeal Standards and Certification Board
13:41:17 v.b3198453