An example

Let’s request data of station AAI (Ambon) in the IA network operated by BMKG, Indonesia. This data is archived at GEOFON but access is restricted to users from a few partner institutes.

  1. The first step is to request a personal token; this can be accomplished by requesting it at https://geofon.gfz-potsdam.de/eas after selecting how long the token will be valid (maximum 1 month).

    -----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

{"valid_until": "2019-05-08T10:21:26.269027Z", "cn": "John Doe",
"memberof": "/epos/experiment2;/epos;/", "sn": "Doe",
"issued": "2019-04-08T10:21:26.269034Z", "mail": "john.doe@gfz-potsdam.de",
"givenName": "John", "expiration": "1m"}
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1

iQEcBAEBAgAGBQJcqyCmAAoJEEFpzp0AlwdXaBQIAL9I7lUriWaoWMDPAnUTLUVE
uA5iQfLwnkano8d18MSjP7ztGx/EO5+NUoutdXCpQFqDXmnk94HbxoOkSkzPPyHO
Tl4FTVSa0/wjdNDG/GsuajZ9zAr0qRTYHGHU1EfcwrhZ/RCYAp9xUzQ4tS6jb0w=
=8kex
-----END PGP SIGNATURE-----

    This token identifies you and can be used for any data from any network you request from GEOFON. Whether you have access to a given network or not is determined by GEOFON operators working with data providers.

    Save the token in your home folder (/home/myusername) under the name .eidatoken. This file should not be accessible to others. Similarly, do not share your token with other users; rather, they should obtain their own using the same service.

    Once you have the token, saved in a file as described above, you can request a username and password for /queryauth using wget, curl or similar tools. Let’s save those credentials in cred.txt.

    • Using wget:

      $ wget --post-file /home/myusername/.eidatoken https://geofon.gfz-potsdam.de/fdsnws/dataselect/1/auth -O cred.txt

    • Using curl:

      $ curl --data-binary @/home/myusername/.eidatoken https://geofon.gfz-potsdam.de/fdsnws/dataselect/1/auth -o cred.txt

    Looking inside this file shows it is fairly harmless:

    cat cred.txt
a1PtiTAJkGpkyJ0MNJKqLrl4:EyFE35kM_WuNUTZP

    These random-looking strings are your temporary username and password. Don’t worry, as you will see below, you don’t have to remember them. Obviously, you should treat these with the same care as any other password, and remove them when not needed.

    In case of problems:

    • “400 Bad Request” - you may not have supplied a correctly formatted token file. Check that you have correctly copied the token from the e-mail you received.

  2. Once you have the credentials, you can use all the FDSNWS tools you normally use, but using the /queryauth method (note “queryauth” not “query” in the examples below. Keep in mind that the credentials have a limited lifetime (typically 24 hours). The cred.txt file contains username and password separated by colon, so you can conveniently use a shell expansion.

    • with wget:

      $ wget "http://`cat cred.txt`@geofon.gfz-potsdam.de/fdsnws/dataselect/1/queryauth?starttime=2015-12-15T16:00:00Z&endtime=2015-12-15T16:10:00Z&network=IA&station=AAI" -O data.mseed

    • or with curl:

      $ curl --digest "http://`cat cred.txt`@geofon.gfz-potsdam.de/fdsnws/dataselect/1/queryauth?starttime=2015-12-15T16:00:00Z&endtime=2015-12-15T16:10:00Z&network=IA&station=AAI" -o data.mseed

    The back quotes (`) above are used to insert the contents of cred.txt into the URL. Either of these commands should request waveform data for ten minutes starting at 4 p.m. on 15 December 2015, saving it in the file data.mseed. (We assume that the network operator has authorized your e-mail address to access station AAI.)

    Possible problems:

    • “204 No Content” - you may have requested a time window and set of streams for which there is no data here. Or you may have requested only channels (and times) for which you do not have permission to access the data.

The fdsnws_fetch tool

Using the fdsnws_fetch program you can combine the request for credentials and the request for data. You can install this tool directly from pip.

$ pip install fdsnwsscripts

You supply the time window and channel information in one command:

$ fdsnws_fetch -s 2015-12-15T16:00:00Z -e 2015-12-15T16:10:00Z -N IA -S AAI -o data.mseed

The token will be automatically loaded and used from the default location /home/myusername/.eidatoken. If it is found there, it will be used. Otherwise, a normal query method will be called and no restricted data will be provided.

Note

fdsnws_fetch is a part of SeisComP3. Documentation is at the SeisComP web site. Finally, fdsnws_fetch has one further advantage - it consults a routing service to discover the URL of the dataselect service and so can be used to retrieve data from more than one data centre at once.

Note

An alternative method of requesting a token is by sending a mail to breqfast@webdc.eu, containing ”.AUTH your_email_address”. The token is sent to the e-mail address you supplied (if you receive the token, you are the verified owner of the address). It is typically valid for 30 days, so you don’t have to request a new token very often. This should only be used in an emergency case, as it contains less information than the suggested method and your data requests could be rejected. Furthermore, this alternative method sends its token via unencrypted e-mail.