fdsnws_fetch

Overview

The fdsnws_scripts, which includes fdsnws_fetch, is a collection of next-generation distributed data request tools that are based on FDSN web services and the EIDA routing service.

You may use these tools to request

• seismic waveform data, as mini-SEED, using the fdsnws-dataselect web service,
• seismic metadata, as FDSN Station XML, using the fdsnws-station web service.

More information about FDSN web services is available at GEOFON and of course from FDSN, at http://www.fdsn.org/webservices/ .

There are three tools here:

1. fdsnws_fetch can request waveform data or metadata, from multiple data centres (access points) with a single command. It does this using the EIDA routing service to discover which data centre(s) holds the data requested.
2. fdsnws2sds supports requests for larger amounts of data, saving it in an SDS tree-like file system structure. (The SeisComP Data Structure is defined in slarchive's documentation and here.)
3. fdsnws2seed provides full SEED and dataless SEED using EIDA FDSN web services. Modern applications should use FDSN StationXML instead of SEED.

Installation

fdsnws_fetch is included in SeisComP 3. A standalone version that consists of only a single Python file that works with Python 2.6, 2.7 and 3.x can be downloaded from here.

Command line options

--version:

show program's version number and exit

-h, --help:

show help message and exit

-l, --longhelp:

show extended help message and exit

-v, --verbose:

verbose mode

-u URL, --url=URL:

URL of routing service (default http://geofon.gfz-potsdam.de/eidaws/routing/1/)

-y SERVICE, --service=SERVICE:

target service (default dataselect)

-N NETWORK, --network=NETWORK:

network code or pattern

-S STATION, --station=STATION:

station code or pattern

-L LOCATION, --location=LOCATION:

location code or pattern

-C CHANNEL, --channel=CHANNEL:

channel code or pattern

-s STARTTIME, --starttime=STARTTIME:

start time

-e ENDTIME, --endtime=ENDTIME:

end time

-q PARAMETER=VALUE, --query=PARAMETER=VALUE:

additional query parameter

-t TIMEOUT, --timeout=TIMEOUT:

request timeout in seconds (default 600)

-r RETRIES, --retries=RETRIES:

number of retries (default 10)

-w RETRY_WAIT, --retry-wait=RETRY_WAIT:

seconds to wait before each retry (default 60)

-n THREADS, --threads=THREADS:

maximum number of download threads (default 5)

-c CREDENTIALS_FILE, --credentials-file=CREDENTIALS_FILE:

URL,user,password file (CSV format) for queryauth

-a AUTH_FILE, --auth-file=AUTH_FILE:

file that contains the auth token

-p POST_FILE, --post-file=POST_FILE:

request file in FDSNWS POST format

-f ARCLINK_FILE, --arclink-file=ARCLINK_FILE:

request file in ArcLink format

-b BREQFAST_FILE, --breqfast-file=BREQFAST_FILE:

request file in breq_fast format

-o OUTPUT_FILE, --output-file=OUTPUT_FILE:

file where downloaded data is written

-z, --no-citation

suppress network citation info

-Z, --no-check

suppress checking received routes and data

Examples

Request 60 minutes of the "LHZ" channel of EIDA stations starting with "A" for a seismic event around 2010-02-27 07:00 (UTC). Optionally add "-v" for verbosity. Resulting Mini-SEED data will be written to file "data.mseed".

$ fdsnws_fetch -N '*' -S 'A*' -L '*' -C 'LHZ' -s "2010-02-27T07:00:00Z" -e "2010-02-27T08:00:00Z" -v -o data.mseed

The above request is anonymous and therefore restricted data will not be included. To include restricted data, use a file containing a token obtained from an EIDA authentication service and/or a CSV file with username and password for each node not implementing the EIDA auth extension.

$ fdsnws_fetch -a token.asc -c credentials.csv -N '*' -S 'A*' -L '*' -C 'LHZ' -s "2010-02-27T07:00:00Z" -e "2010-02-27T08:00:00Z" -v -o data.mseed

StationXML metadata for the above request can be requested using the following command:

$ fdsnws_fetch -N '*' -S 'A*' -L '*' -C 'LHZ' -s "2010-02-27T07:00:00Z" -e "2010-02-27T08:00:00Z" -y station -q level=response -v -o station.xml

Multiple query parameters can be used:

$ fdsnws_fetch -N '*' -S '*' -L '*' -C '*' -s "2010-02-27T07:00:00Z" -e "2010-02-27T08:00:00Z" -y station -q format=text -q level=channel -q latitude=20 -q longitude=-150 -q maxradius=15 -v -o station.txt

Bulk requests can be made in ArcLink (-f), breq_fast (-b) or native FDSNWS POST (-p) format. Query parameters should not be included in the request file, but specified on the command line.

$ cat >req.arclink
2010,02,18,12,00,00 2010,02,18,12,10,00 GE WLF BH*
2010,02,18,12,00,00 2010,02,18,12,10,00 GE VSU BH*

$ fdsnws_fetch -f req.arclink -y station -q level=channel -v -o station.xml

In order to access restricted data, you need an authentication token that can be obtained by sending an email to breqfast@webdc.eu, containing

.AUTH your_email_address

The location of token file can be specified with "-a"; if ${HOME}/.eidatoken exists, it is used by default.

    fdsnws_scripts are free software: you can redistribute it and/or modify
    it under the terms of the GNU Lesser General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    fdsnws_scripts are distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU Lesser General Public License for more details.

    You should have received a copy of the GNU Lesser General Public License
    along with fdsnws_scripts.  If not, see <http://www.gnu.org/licenses/>.

© Helmholtz Centre Potsdam - GFZ German Research Centre for Geosciences