NetDC - Example Request
NetDC is a powerful tool for accessing seismic data from one or more data centers. There are 3 types of NetDC requests: inventory, response or waveform data. Here we provide a simple example including each. The IPGP Data Center also has several nice examples of NetDC requests which illustrate the syntax and range of requests.
Here is an example of a NetDC request:
.NETDC_REQUEST .NAME Lind Gee .INST UC Berkeley .EMAIL firstname.lastname@example.org .LABEL Test_Example .MEDIA FTP .FORMAT_WAVEFORM SEED .FORMAT_RESPONSE SEED_ASCII .MERGE_DATA NO .END .INV * * * .RESP * "G BK GE IU II" * * "LH? BHZ" "2001 01 01 00 00 00.000" "2002 01 01 01 00 00.000" .DATA * * * * LH? "2001 06 23 20 30 00.000" "2001 06 24 00 30 00.000" .DATA * * * * BHZ "2001 06 23 20 30 00.000" "2001 06 23 21 30 00.000"
This request was sent to email@example.com, but could have been sent to any of the data centers. NetDC responds with an acknowledgement of the request via email
Your NETDC request has been received and is currently in the processing system. You will be notified when your data product is ready. Received by: NCEDC Assigned request HUB_ID: NCEDC:Jan_11,02:02:12:25373 With request label: Test_Example Requested by: Lind_Gee (firstname.lastname@example.org) Merge Requested?: No Virtually yours, The NETDC request processor (v1.0.4beta2)
In general, the request can be broken into two parts - the boiler plate which provides information about the user and data transmission and the request lines. The .END key divides the boiler plate from the request lines.
- NetDC boiler plate
.NETDC_REQUEST .NAME Lind Gee .INST UC Berkeley .EMAIL email@example.com .LABEL Test_Example .MEDIA FTP .FORMAT_WAVEFORM SEED .FORMAT_RESPONSE SEED_ASCII .MERGE_DATA NO .END
The first part of the request is the NetDC "boiler plate" - identification of the user (.NAME Lind Gee and .INST UC Berkeley), an email address for response (.EMAIL firstname.lastname@example.org), a label to make it easier to sort out multiple requests (.LABEL Test_Example), and identification of acceptable media and formats (.MEDIA FTP, .FORMAT_WAVEFORM SEED and .FORMAT_RESPONSE SEED_ASCII). Optionally, the user can include additional contact information (such phone and fax numbers). The .MERGE_DATA entry defines whether the results of the request will be combined at the data center where the request originated or whether each data center should ship the results separately. .MERGE_DATA NO means that no merging will be performed; if the user is interested in receiving a single package, the user needs to specify a time window (in days) over which the results will be compiled - for example, .MERGE_DATA YES 2. The termination of the boiler plate is identified by the .END key word.
Warning - if you cut and paste from the example above, please be sure to change the .NAME, .INST, and .EMAIL. I don't want to receive your data!
- NetDC request lines
NetDC request lines follow a general form:
.<DATA_TYPE> <DATA_CENTER> <NETWORK> <STATION> <LOCATION> <CHANNELS> <START_TIME> <END_TIME>
where the DATA_TYPE may be inventory (INV), response (RESP), or waveform data (DATA). A request may designate one or more data centers for the request - or use a wildcard for all. The remainder of the request is the specification of the data or information required using the SEED (Standard for the Exchange of Earthquake Data) nomenclature of network, station, location, and channel codes and start and end times.
Inventory requests allow queries about data holdings by data center, network, station, or channel. In this example, the inventory command is very simple:
.INV * * *
where .INV * * * requests information about every station in every network available at every participating data center. The inventory command is the only request command which accepts a variable number of arguments - for example .INV * returns information on which data centers are participating and .INV * * returns information on all networks available at all data centers.
This inventory request returned the following information:
- INVENTORY SHIPMENT from the Geoscope Data Center
- INVENTORY SHIPMENT from the IRIS Data Center
- INVENTORY SHIPMENT from the NCEDC
- INVENTORY SHIPMENT from the Geofon Data Center
Since the file from the IRIS Data Center was large, it was made available by ftp. Note that since the request did not specify a time period, information was returned on stations which are closed - as well as operating.
The .RESP command returns channel instrument response. Like the .DATA command, all arguments must be fully specified in order to return information
.RESP * "G BK GE IU II" * * "LH? BHZ" "2001 01 01 00 00 00.000" "2002 01 01 01 00 00.000"
The first token in this .RESP line is a wildcard that indicates that all data centers should be queried. The second token specifies the networks of interest - and in this example I indicated 5 separate networks, using a space to separate entries and "" to enclose the entire string. The 3rd and 4th tokens are wildcards to return information for all station and locations codes, but the 5th token specifies the LH? and BHZ data channels (note the space separation and the quotes). The last two arguments indicate the time period for which the instrument response is requested.
This response request returned the following information:
- RESPONSE SHIPMENT from the Geoscope Data Center
- RESPONSE SHIPMENT from the IRIS Data Center
- RESPONSE SHIPMENT from the NCEDC
In this case, the NCEDC and IRIS facilities produced large files for ftp. The initial request specified SEED_ASCII as the format for the responses, but it is the only supported format at this time.
Helpful hint - Always count your tokens. One of the most common mistakes is to leave out a token. I made it several times in constructing this example! And watch out for the quotation marks!
The .DATA request returns waveform data. As described for the .RESP line, all arguments must be fully specified in order to return data.
.DATA * * * * LH? "2001 06 23 20 30 00.000" "2001 06 24 00 30 00.000" .DATA * * * * BHZ "2001 06 23 20 30 00.000" "2001 06 23 21 30 00.000"
In this example, I have made two data requests, one for LH? and one for BHZ. Since I am interested in different time periods for each, they are separate request lines. This example uses wildcards for the data center, network, and station entries in order to request LH data from all stations operating during the 06/23/2001 Peru earthquake of M8.4 (the ? matches any single character and so returns LHZ, LHN, LHE, LH1, LH2, LH3, etc). I requested 4 hours of data. The BHZ request uses the same wild cards
The initial request specified SEED output, which is the only format supported at the present. I have not linked the resulting SEED files here.
Helpful Hint - one should always be prudent in making requests for waveform data. Be careful what you ask for!
Good luck with using NetDC! For more help, see the resources below: