An example

Let’s request data of station LISJ (Al-Lesan) in the Jordanian Seismological Network operated by JSO. 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": "2024-05-08T10:21:26.269027Z", "cn": "Matilde Username",
"memberof": "/epos/experiment2;/epos;/", "sn": "Username",
"issued": "2024-04-08T10:21:26.269034Z", "mail": "Matilde.User@gfz-potsdam.de",
"givenName": "Matilde", "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 directory (e.g. /home/myusername) under the name “.eidatoken” (note the dot). 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. (In the rest of this example, replace /home/myusername with the path to your own home directory. You can find that by typing cd ; pwd or echo ~.)

    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 when saving it to the file.

  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=2020-06-16T14:00:00Z&endtime=2020-06-16T15:00:00Z&network=JS&station=LISJ" -O data.mseed

    • or with curl:

      $ curl --digest "http://`cat cred.txt`@geofon.gfz-potsdam.de/fdsnws/dataselect/1/queryauth?starttime=2020-06-16T14:00:00Z&endtime=2020-06-16T15:00:00Z&network=JS&station=LISJ" -o data.mseed

    The back quotes (`) above are used to insert the contents of cred.txt into the URL. (Your shell may prefer $(cat cred.txt) instead of back quotes.) Either of these commands should request waveform data for sixty minutes starting at 2 p.m. on 16 June 2020, saving it in the file data.mseed. (We assume that the network operator has authorized your e-mail address to access station LISJ.)

    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.

    • “401 Unauthorized” - your username and password couldn’t be read from the credentials file, or were incorrect.

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.

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 2020-06-16T14:00:00Z -e 2020-06-16T15:00:00Z -N JS -S LISJ -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 SeisComP. 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.

The ObsPy framework

In ObsPy the RoutingClient supports providing a token (since version 1.1). Simply pass the name of your token file when you create a RoutingClient instance:

>>> from obspy.clients.fdsn import RoutingClient
>>> from obspy import UTCDateTime

>>> rsClient = RoutingClient("eida-routing", credentials={'EIDA_TOKEN': '/home/myusername/.eidatoken'})
>>> st = rsClient.get_waveforms(network="JS", station="LISJ", channel="SHZ", starttime=UTCDateTime(2020, 6, 16), endtime=UTCDateTime(2020, 6, 16, 15, 0, 0))
>>> print(st)

71 Trace(s) in Stream:

JS.LISJ..SHZ | 2020-06-16 - 2020-06-16T00:16:01.540000Z | 50.0 Hz, 1296 samples

(70 other traces)...

If this does not work you can turn on debugging at the moment of the client creation:

>>> rsClient = RoutingClient("eida-routing", debug=True, credentials= ...)

You will probably receive the HTTP error “403 Forbidden” if you are not authorized to download the requested stream(s).

The Pyrocko framework

Pyrocko is another seismological Python framework. It is capable of retrieving waveform data from GEOFON, and is token-aware.

>>> from pyrocko.client import fdsn
>>> from pyrocko import util

>>> starttime = util.stt("2020-06-16 15:00:00.000")
>>> endtime = util.stt("2020-06-16 16:00:00.000")
>>> selection = [("JS", "LISJ", "*", "*", starttime, endtime)]

>>> token = open("/home/myusername/.eidatoken", "rb").read()
>>> req = fdsn.dataselect(site="geofon", selection=selection, token=token)

Again, you will probably see the HTTP error “403 Forbidden” if you are not authorized to download the requested stream(s).