Manuals: NetDC


Important Note: NetDC has been deprecated at the DMC and was shut down on October 1st, 2013
Any email to netdc@fdsn.org now redirects to NCEDC’s installation of NetDC.

NAME

NetDC – Networked Data Center Protocol

DESCRIPTION

NetDC is a data request system that allows a user to request seismological information from multiple data centers through a single email form. Information is delivered to the user through email and FTP in a uniform digital or text format.

REQUEST FORMAT

A NetDC request has a similar layout to the familiar BREQ_FAST request format, which has already been in use at various data centers for several years. Below is the general layout of the NetDC request. Some of the fields are mandatory. Note that fields may be separated by spaces, tabs, or both (collectively referred to as white-space).

.NETDC_REQUEST
.NAME    <name of user requesting data>
.INST    <name of institution>
.MAIL    <return mailing address>
.EMAIL    <return email address>
.PHONE    <phone number>
.FAX    <fax number>
.LABEL    <user-assigned label for request>
.MEDIA    <primary media selection>
.ALTERNATE MEDIA    <alternate media selection>
.FORMAT_WAVEFORM    <what format to receive waveform traces in>
.FORMAT_RESPONSE    <what format to receive response information in>
.MERGE_DATA    <YES or NO and waiting time>
.DISPOSITION    <instructions for FTP data transfer to user>
.END
<data request line #1>
<data request line #2>
<data request line #3>
…
<data request line #N>

Format Explained

.NETDC_REQUEST (mandatory)


This is a tag that identifies the mail document as a request intended for NetDC. This must always be the first line of the request.

.NAME (mandatory)

Indicates the name of the user. This is needed to identify the request and allows for the grouping of multiple requests by the same user.

.INST (mandatory)

Lists the institution that the user belongs to. This can be a company name, educational institution or any organization. This assists in establishing contact with the user should it be necessary for servicing the request.

.MAIL

Indicates the postal address of the institution, should it be necessary to send physical media containing the requested information.

.EMAIL (mandatory)

This is the email address of the requesting user. This entry is mandatory since the majority of user contact will be through email.

.PHONE

Lists the user’s contact phone number.

.FAX

Indicates the fax machine number that the user has access to.

.LABEL

This is a user-assigned label for the request, which will appear in data files shipped to the user. If a label is not specified, a default value will be assigned.

.MEDIA

Specifies the preferred media of delivery of the data. Normally the media type will be predetermined by the type and size of the data being shipped. Options are currently FTP, EMAIL, EXABYTE TAPE, DAT TAPE, DLT TAPE, and possibly others.

.ALTERNATE MEDIA

Specifies a backup media option should the first not be available.

.FORMAT_WAVEFORM

Indicates the format for the waveform data to be shipped. Currently, the only option is SEED. SEED will also be the default format if this line is not provided.

.FORMAT_WAVEFORM SEED

.FORMAT_RESPONSE

Indicates the format for response information when it is requested. The current default is SEED ASCII, which is a specific text output format for displaying response data known as RESP format.

.FORMAT_RESPONSE SEED_ASCII

.MERGE_DATA

Requires a YES or NO entry, specifying whether the data products should be combined at the hub data center (i.e. the data center to which the original data request was sent) before shipment to the user or if each data center should send their shipment to the user individually. In the case of a YES entry, a number of days should be entered which equates to the wait time in days. After that point, the hub data center will ship what it is able to provide and any late shipments will be redirected to the user. Here is an example of how the user would specify product merging with a two-day time window.

.MERGE_DATA YES 2

.DISPOSITION

This is an optional field for specifying how to transfer data through FTP to the user. It will be followed by one of two directives: PUSH or PULL. The PUSH case directs the data center performing the shipment to open an FTP dialogue with the user’s host machine and put the data on the user’s machine. The PUSH directive is followed by the host name and the anonymous FTP directory into which the data is placed.:

.DISPOSITION PUSH myhost.seismology.edu /pub/dropoff

The PULL directive specifies that the user will get the data through FTP manually once notified by email that it is available. There is no need to specify a host name or directory here:

.DISPOSITION PULL

.END (mandatory)

This is the entry that signals the end of the request header. What follows the .END tag is one to many data request lines, which list specifically what data the user wants to receive. There is no set limit to the number of data request lines a user can enter, but each line must be a separate record with white space separators for each of the fields.

Request Lines

The data request lines come in three flavors: .DATA, .RESP, and .INV. .DATA lines request waveform data, .RESP lines ask for response information, and .INV queries a site for an inventory of data holdings. All of these request types follow the same general format, even though the response to each will differ.

Each request line is a separate entity consisting of white-space separated fields. Each field in the request line is a text string where the first field contains a leading period. UNIX-style wildcards ? and * can be used in many of the field strings, which indicate “match to any one character” and “any number of characters”, respectively. The field layout of a data request line is as follows:

.<DATA_TYPE> <DATA_CENTER> <NETWORK> <STATION> <LOCATION> <CHANNELS> <START_TIME> <END_TIME>

To elaborate:

DATA_TYPE

Specifies what data are desired. This field must always have a leading period, making the possible choices .DATA, .RESP, and .INV. Note that more data types may become available in the future.

DATA_CENTER

This is a unique string identifier representing a specific data center in the group of networked data centers. The proper data center code name must be used here in order to match to the proper data center.This field may be wild carded with a single *. However, if the user insists that data come from a specific data center, then putting an identifier in this field would force the request line to be sent to that site. (Here is a list of all the networks and the data centers that act as the primary providers – it looks like <network code>|<data center> ).

NETWORK

This is the FDSN network code (list) for the data requested, consisting of one or two characters. This field may be wild carded.

STATION

This is a station name up to five characters in length. This name refers to a geographic location, so occasionally another network will have the same station name for their instrument placed nearby. This is equivalent to the station identifier in SEED format. The number of station names can vary from one to any number of white-space separated elements. Each station entry may be wild carded. When two or more stations are specified, they need to be enclosed in double-quotes. An example station string would be:

"ANMO KIV B*"

LOCATION

This is an identifier that allows users to request data from specific data streams on the instrument at the specified network and station. This is in the form of a one or two character string, referring to the location identifier in SEED format. This field may be wild carded. The number of location identifiers can vary from one to any number of white-space separated elements. Each location identifier entry may be wild carded. When two or more location identifiers are specified, they need to be enclosed in double quotes. An example location string would be:

"00 01 02"

CHANNELS

This is a string describing the channels to be retrieved. Channel names are up to three characters in length and follow SEED channel-naming conventions. The number of channel names can vary from one to any number of white-space separated elements. Each channel entry may be wild carded. When two or more channels are specified, they need to be enclosed in double-quotes. An example channel string would be:

"BHE LH? E*"

START_TIME

This is a six-field set of numbers specifying the time and date for the beginning of the time window desired. The format is:

"YYYY MM DD hh mm ss.ffff"

where:

YYYY = year (0000-9999)
MM = month (01-12)
DD = day of month (01-31)
hh = hour (00-23)
mm = minute (00-59)
ss = second (00-59)
ffff = fraction of second (0000-9999 ten-thousandths)

Take note that the ss field can drop the decimal point if the fraction of a second is equal to zero. Since this is a white-space separated set of characters, the time string must be contained within double-quotes. Wildcards are not allowed. An example start time could be:

"1995 06 22 04 00 23.4522"

END_TIME

This has the same format as START_TIME, and pertains to the end of the time window for the data desired.

Request Types

Inventory Requests

Inventory (.INV) requests ask for information regarding the data holdings of a particular data center. Examples of .INV request lines:

.INV *
.INV GEOFON *
.INV GEOFON AA B*
.INV GEOFON AA TATO * *
.INV * IU "AAE ANMO" * * "1995 03 03 02 24 01.3" "1995 03 03 07 00 30.0"
.INV * II KIV * "BHE BHN BHZ" "1996 05 01 00 00 00.0" "1996 05 01 05 00 00.0"

Looking at these sample inventory requests, you’ll notice that some of the request lines have less than the total number of fields filled in. What this illustrates is the inventory request’s unique ability to accept a variable number of field entries which will determine how much information is returned. Information is displayed hierarchically. That is, what you don’t include in your request line – either explicitly or with wildcards – you don’t get. So, in our above example, the first request line would only return a list of cooperating Data Centers, the second a list of networks for the specified Data Center, the third line a list of stations from network AA that begin with a B, etc., following the request line format listed earlier in this section.

Response Requests

Response (.RESP) requests return detailed station and channel information to the user in the form of a specially formatted ASCII text file. The format mimics response files generated by the IRIS utility rdseed. Unlike .INV request lines, the .RESP lines must include all the field strings in the standard request line format. Example of a .RESP request line:

.RESP * G SSBC * * "1990 03 01 00 00 00" "1990 03 02 00 00 00"

Waveform Requests

A request for waveform data (.DATA) may take considerably longer to process than requests for inventory and response data. If the user has mixed inventory or response request lines with waveform request lines, the inventory and response data will generally be returned sooner than waveform data. Unlike inventory requests, all fields must be included in a .DATA request line, including the start and end time, in order for the request line to be accepted. The default output format for waveform data is binary SEED format. Example of a .DATA request line:

.DATA * II BFO * BHZ "1998 02 03 04 20 34" "1998 03 04 20 20 00"

MAILING A REQUEST

A NetDC request is completed by emailing the request to:

netdc@fdsn.org

Alternatively, the request can be emailed directly to user-id netdc at any participating data center.

EXAMPLE REQUEST

.NETDC_REQUEST
.NAME Joe Seismologist
.INST University of Quakes
.MAIL 1101 Binary Data Way, Anytown, WA 90909
.EMAIL joe@host.seismolab.edu
.PHONE (999) 555-4567
.FAX (999) 555-4568
.LABEL My_Request
.MEDIA FTP
.ALTERNATE MEDIA EXABYTE 2GB
.FORMAT_WAVEFORM SEED
.FORMAT_RESPONSE SEED_ASCII
.MERGE_DATA YES 3
.DISPOSITION PULL
.END
.RESP * G SSBC * * "1990 03 01 00 00 00" "1990 03 02 00 00 00"
.INV NCEDC * *
.DATA * PS TSKO * M?? "1990 03 01 00 00 00" "1990 03 05 06 02 45.78"
.DATA * CD ZHLP * "B?? S??" "1986 06 16 00 00 00" "1986 06 19 04 00 00"

NETWORK CODES & DATA CENTERS

View a list of network codes and data centers

See Also

Release date:     Modified date: