Using the FDSN web services at GEOFON

Overview

GEOFON offers access to seismic waveform and station metadata using the FDSN web services, from geofon.gfz-potsdam.de:

fdsnws-station
Inventory for all networks archived at GFZ. A current list of networks is available. In particular, networks which are coordinated as part of EIDA but not archived here are not available by web service. Their metadata can be accessed using our data portal or by other methods.
fdsnws-dataselect
Real time and archive data for those networks archived at GFZ (not other EIDA data centres). You can check availability with our availability database or the WFcatalog service, or fdsnws-availability (see below).
fdsnws-event
The earthquake parameter service serves event information as QuakeML and plain text.
fdsnws-availability
Time series data availability as text, JSON or CSV.

A few example URLs for the FDSN web services are given below.

fdsnws-station

http://geofon.gfz-potsdam.de/fdsnws/station/1/version
Returns the string "1.1.4".
http://geofon.gfz-potsdam.de/fdsnws/station/1/query?net=GE&level=station
Returns basic information as FDSN StationXML about all stations in the GEOFON seismic network.
http://geofon.gfz-potsdam.de/fdsnws/station/1/query?net=GE&level=station&format=text
Returns much of the same information as the previous example, but by adding "&format=text" to the query string (after the "?"), the result is presented as plain text, separated by "|".
http://geofon.gfz-potsdam.de/fdsnws/station/1/query?net=GE&sta=BKB&cha=BHZ&level=channel
Returns channel-level information as FDSN StationXML for the BHZ channel at GEOFON station Balikpapan, Kalimantan.
http://geofon.gfz-potsdam.de/fdsnws/station/1/query?net=GE&cha=BH?&start=2016-01-01&level=response
Returns response-level information as FDSN StationXML for all BH* channels present at all current GEOFON stations. This may be imported directly into SeisComP. Warning: this is relatively large (> 4MB).

For many temporary networks, the FDSN-assigned network code is shared between multiple networks. For these you may need to specify a year range to avoid unwanted unrelated stations. Our list of networks archived at GEOFON includes the start and end year for each network. The next example shows this:

http://geofon.gfz-potsdam.de/fdsnws/station/1/query?net=3D&level=station&format=text&start=2014-01-01&end=2016-12-31
Metadata for the HART-PISAGUA Project Chile, in operation from 2014 to 2016. Without providing "&start=...", data for all of our networks with code 3D would be returned.

fdsnws-dataselect

http://geofon.gfz-potsdam.de/fdsnws/dataselect/1/version
Returns the string "1.1.1".
http://geofon.gfz-potsdam.de/fdsnws/dataselect/1/query?net=GE&sta=BKB&cha=BHZ&starttime=2011-03-11T06:00:00Z&endtime=2011-03-11T06:05:00Z
Requests 300 seconds of data from 0600 UTC on 11 March 2011, for the BHZ channel at GEOFON station Balikpapan, Kalimantan. See the note below.
http://geofon.gfz-potsdam.de/fdsnws/dataselect/1/query?net=GE&sta=KBU&starttime=2012-06-01&endtime=2012-06-04&nodata=404
Requests data from the GEOFON station in Kabul, Afghanistan; since this is not available, the service returns "404 Not Found" instead.

fdsnws-event

http://geofon.gfz-potsdam.de/fdsnws/event/1/version
Returns the string "1.2.5".
http://geofon.gfz-potsdam.de/fdsnws/event/1/query?format=text&start=2021-01-01T00:00:00&end=2021-01-01T12:00:00
Requests a list of events occuring in the first twelve hours of 2021 (UTC). Note specification of "&format=text" in the query string (after "?" in the URL above). Response is a text (CSV) file, with columns separated by the "|" character. There are seven events. The first row is a header, displaying the meaning of each column. We do not yet use the EventType parameter to distinguish between types of event, so they are all reported as "earthquake".
http://geofon.gfz-potsdam.de/fdsnws/event/1/query?start=2016-12-21&end=2016-12-26&maxlat=30&maxlon=150&minmag=5&format=text
Requests a list of events between 21 and 25 December 2016 (inclusive). Additional parameters in the "query string" (after "?" in the URL above) serve to constrain the set of events selected by geographical region and magnitude. As above, the response is a text (CSV) file, with columns separated by the '|' character. There are currently 12 events matching the selection criteria.
http://geofon.gfz-potsdam.de/fdsnws/event/1/query?eventid=gfz2021adkh
Requests basic QuakeML for the event gfz2021adkh.
http://geofon.gfz-potsdam.de/fdsnws/event/1/query?eventid=gfz2021adkh&includefocalmechanism=true
Requests QuakeML for the same event as above, but adds "includefocalmechanism=true". The response is the same as above but now includes information about the preferred published focal mechanism(s), if there is one.
http://geofon.gfz-potsdam.de/fdsnws/event/1/query?eventid=gfz2015sfdd&includeallfocalmechanisms=true
Requests QuakeML for the event gfz2015sfdd but adds "includeallfocalmechanisms=true". The response now includes all published focal mechanism(s). For GEOFON events currently there is not more than one focal mechanism per event. Our service includes several similar additional request parameters which are extensions of the FDSN specification. For details, see here.

fdsnws-availability

http://geofon.gfz-potsdam.de/fdsnws/availability/1/version
Returns the string "1.0.3".
http://geofon.gfz-potsdam.de/fdsnws/availability/1/query?format=text&net=GE&cha=BHZ&start=2021-01-01T00:00:00&end=2021-01-01T12:00:00
Requests a list of BHZ channels at stations in the GE network with data available in the first twelve hours of 2021 (UTC).

Access to restricted data with webservices

Stations with restricted channels are available through the auth extension to FDSN webservices.

Notes

  1. The current implementation supports the Web Services Version 1.2 Specification. There are a few special features, described further at the SeisComP online documentation for fdsnws [Specific page for the 4.7.3]. In particular you may add &nodata=404 to return a HTTP response code 404 instead of the usual 204, should no data be found.
  2. There are some limits on the size of requests which will be accepted:
    • There is a maximum number of objects which fdsnws-station will return. This is currently 250000 objects.
    • There is a maximum number of objects which fdsnws-event will return. This is also currently 250000 objects. The note below gives additional details.
    • There is a maximum number of samples which fdsnws-dataselect will return. This is currently 1000 million samples.
    There are also some limits on the total number of simultaneous users. If you plan to send many automatic requests, please arrange to send them slowly to avoid inconveniencing other users.
  3. The /auth method allows access using token-based authentication. See FDSN web services authentication and authorization at GEOFON.
  4. The actual data returned depends on availability.
  5. Assuming we have complete data for the time window you request, the fdsnws-dataselect service will send you unmodified mini-SEED records covering all the time you have requested (see figure).
    Demonstrate mini-SEED records returned in response to a time window request
    Each mini-SEED record is generally 512 bytes, and contains a variable number of samples (depending on compression and sample rate). For BH (20 samples per second) data, a record may cover a time segment of around 10-20 seconds. It does not start or end at the time you request, in general. If you request data with start_time=tstart, you will receive the entire mini-SEED record which includes tstart for each channel. Such records, and those at the end of the time window tend, are shown in bright green in the figure above. Thus you will receive data corresponding to the dark green and light green regions, but not the yellow regions. Note that the time windows returned may differ between channels (BHE, BHN, BHZ above), and may contain gaps or overlaps.

  6. Size limits for fdsnws-event. You can request the entire set of GEOFON events as a text (CSV) file with a single request, using format=text. For the richer QuakeML output more care is needed. The number of events you can receive in a single request depends on the web service options you employ in your request.

    To ensure adequate capacity for all users of our service, we have limits on request size in place. These are implemented as a limit on the total number of objects involved, which is much greater than the number of events, as it can include many origins, magnitudes, focal mechanisms, picks, for each event. This is related to the size of the event - larger events, detected at more stations, and with more analysis, generate more objects than small ones.

    If your request is too large, then the server responds with

    Error 413: Request Entity Too Large

    In particular, a request to the /query method with no restrictions at all (https://geofon.gfz-potsdam.de/fdsnws/event/1/query) will result in this 413 error.

    As a guide, the following requests should be successful:

    • Default XML will work for up to a few thousand events, such as a year of our bulletin. The response includes only the preferred origin and magnitude, and no picks or focal mechanisms. For example, the http://geofon.gfz-potsdam.de/fdsnws/event/1/query?start=2020-01-01&end=2021-01-01 response (9.4 MB) contains all 4715 events in 2020.

    • With focal mechanisms: (Options: includeallfocalmechanisms=true). An entire year also succeeds. The GEOFON data set includes focal mechanisms for around 20% of events.

    • With picks. (Options: includearrivals=true&includepicks=true). An entire month of events generally succeeds. For example, http://geofon.gfz-potsdam.de/fdsnws/event/1/query?includearrivals=true&includepicks=true&start=2020-11-01&end=2020-12-01 is 369 events with 19891 picks (15.5 MB) in December 2020.

    • With both picks AND focal mechanisms requested, even a time span of a month is too long. Confining ourselves to the largest magnitude events (those with the most objects) only, but with no time constraint (i.e. includeallfocalmechanisms=true&includefocalmechanism=true&includearrivals=true&includepicks=true&minmag=...), succeeds for large enough magnitudes. Currently the smallest magnitude for which the request above succeeds is around M=6.6; this contains 494 events, is 88 MB, and takes over six minutes. Values of minmag smaller than this in the request result in the 413 error response. For M=7.0, there are 211 events in a 40MB XML response file.