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 sending e-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. The e-mail message has a subject like “FSDNWS auth token” and will look something like this:

    Dear user,
    
    
    below is your FDSNWS auth token. It is valid for 30 days.
    
    -----BEGIN PGP MESSAGE-----
    Version: GnuPG v2.0.9 (GNU/Linux)
    
    owEBfgGB/pANAwACAdESVVjLmBQAActOYgBYKaGkeyJtYWlsIjogInBldmFuc0Bn
    ZnotcG90c2RhbS5kZSIsICJ2YWxpZFAK3nRpbCI6ICIyMDE2LTEyLTE0VDExOjM2
    XGWTu888+5UYeOP8NXeN3L/COe8isH6YsnbbB4y4NQANrHELRVs60/UZNSUjs8Tx
    9bpwlVAnoDrQrKeIUQYp8k77CaDWxtZUAye6Y1xJ0EUWUOgCsRUZgxRAtCXQxukM
    HI6Xt/JAMfFvNxzHsRm4SdEgAVD9QnWdGN67brYRXE+5x06yQqXTvTEl5UqSTJlO
    bb9LBrsh97Yu6ir/tNg/+qtq43KI3cHtpBu0oah9MezyFQyPb1M7t+MCmmAfNpTe
    KdTYdvU=
    =lYsv
    -----END PGP MESSAGE-----
    

    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 part between “—–BEGIN PGP MESSAGE—–” and “—–END PGP MESSAGE—–” (including those two lines) in a file called token.asc somewhere. 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 file token.asc), 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 token.asc https://geofon.gfz-potsdam.de/fdsnws/dataselect/1/auth -O cred.txt
      
    • Using curl:

      $ curl --data-binary @token.asc 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.

New fdsnws_fetch tool

Using the fdsnws_fetch program you can combine the request for credentials and the request for data. Get the Python fdsnws_fetch.py script from the EIDA/seiscomp3 repository at github.com. You supply your token and the time window and channel information in one command:

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

Note the use of the ‘-a’ option to tell fdsnws_fetch where your token is.

Note

fdsnws_fetch is a part of SeisComP, which will be included in future releases. 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.