# obspy.clients.fdsn - FDSN web service client for ObsPy

The obspy.clients.fdsn package contains a client to access web servers that implement the FDSN web service definitions.

copyright: | The ObsPy Development Team (devs@obspy.org)
license: | GNU Lesser General Public License, Version 3 (https://www.gnu.org/copyleft/lesser.html)

Contents

- Basic FDSN Client Usage
- Basic Routing Clients Usage
- Classes & Functions
- Modules

## Basic FDSN Client Usage

The first step is always to initialize a client object.

    >>> from obspy.clients.fdsn import Client
    >>> client = Client("IRIS")

A client object can be initialized either with the base URL of any FDSN web service or with a shortcut name which will be mapped to a FDSN URL. All the example make use of the FDSN web service at IRIS. For a list of other available web service providers, see the `__init__()` method. The currently available providers are:

    >>> from obspy.clients.fdsn.header import URL_MAPPINGS
    >>> for key in sorted(URL_MAPPINGS.keys()):
    ...     print("{0:<7} {1}".format(key,  URL_MAPPINGS[key]))
    BGR     http://eida.bgr.de
    EMSC    http://www.seismicportal.eu
    ETH     http://eida.ethz.ch
    GEONET  http://service.geonet.org.nz
    GFZ     http://geofon.gfz-potsdam.de
    ICGC    http://ws.icgc.cat
    INGV    http://webservices.ingv.it
    IPGP    http://ws.ipgp.fr
    IRIS    http://service.iris.edu
    ISC     http://isc-mirror.iris.washington.edu
    KNMI    http://rdsa.knmi.nl
    KOERI   http://eida.koeri.boun.edu.tr
    LMU     http://erde.geophysik.uni-muenchen.de
    NCEDC   http://service.ncedc.org
    NIEP    http://eida-sc3.infp.ro
    NOA     http://eida.gein.noa.gr
    ODC     http://www.orfeus-eu.org
    ORFEUS  http://www.orfeus-eu.org
    RESIF   http://ws.resif.fr
    SCEDC   http://service.scedc.caltech.edu
    TEXNET  http://rtserve.beg.utexas.edu
    USGS    http://earthquake.usgs.gov
    USP     http://sismo.iag.usp.br

1. `get_waveforms()`: The following example illustrates how to request and plot 60 minutes of the `"LHZ"` channel of station Albuquerque, New Mexico (`"ANMO"`) of the Global Seismograph Network (`"IU"`) for an seismic event around 2010-02-27 06:45 (UTC). Results are returned as a `Stream` object. See the `get_waveforms_bulk()` method for information on how to send multiple requests simultaneously to avoid unnecessary network overhead.

       >>> from obspy import UTCDateTime
       >>> t = UTCDateTime("2010-02-27T06:45:00.000")
       >>> st = client.get_waveforms("IU", "ANMO", "00", "LHZ", t, t + 60 * 60)
       >>> st.plot()

   (Source code, png, hires.png)

2. `get_events()`: Retrieves event data from the server. Results are returned as a `Catalog` object.

       >>> starttime = UTCDateTime("2002-01-01")
       >>> endtime = UTCDateTime("2002-01-02")
       >>> cat = client.get_events(starttime=starttime, endtime=endtime,
       ...                         minmagnitude=6, catalog="ISC")
       >>> print(cat)
       2 Event(s) in Catalog:
       2002-01-01T11:29:22.720000Z |  +6.282, +125.749 | 6.3 MW
       2002-01-01T07:28:57.480000Z | +36.991,  +72.336 | 6.3 Mb
       >>> cat.plot()

   (Source code, png, hires.png)

3. `get_stations()`: Retrieves station data from the server. Results are returned as an `Inventory` object.

       >>> inventory = client.get_stations(network="IU", station="A*",
       ...                                 starttime=starttime,
       ...                                 endtime=endtime)
       >>> print(inventory)
       Inventory created at ...
           Created by: IRIS WEB SERVICE: fdsnws-station | version: ...
                       ...
           Sending institution: IRIS-DMC (IRIS-DMC)
           Contains:
                   Networks (1):
                           IU
                   Stations (3):
                           IU.ADK (Adak, Aleutian Islands, Alaska)
                           IU.AFI (Afiamalu, Samoa)
                           IU.ANMO (Albuquerque, New Mexico, USA)
                   Channels (0):
       >>> inventory.plot()

   (Source code, png, hires.png)

## Basic Routing Clients Usage

Routers are web services that can be queried for which data centers offer certain pieces of data. That information can then be used to get the actual data from various data center across the globe. All current routing services only support the `dataselect` and the `station` FDSNWS services.

ObsPy has support for two routing services:

1. The IRIS Federator.
2. The EIDAWS Routing Service.

To use them, call the `RoutingClient()` function:

    >>> from obspy.clients.fdsn import RoutingClient

Get an instance of a routing client using the IRIS Federator:

    >>> client = RoutingClient("iris-federator")
    >>> print(type(client))
    <class '...fdsn.routing.federator_routing_client.FederatorRoutingClient'>

Or get an instance of a routing client using the EIDAWS routing web service:

    >>> client = RoutingClient("eida-routing")
    >>> print(type(client))
    <class '...fdsn.routing.eidaws_routing_client.EIDAWSRoutingClient'>

They can be used like the normal FDSNWS clients, meaning the `get_(waveforms|stations)(_bulk)()` functions should work as expected.

To be able to do geographic waveform queries with the EIDA service, ObsPy will internally perform a station query before downloading the waveforms. This results in a similar usage between the EIDA and IRIS routing services from a user’s perspective.

The following snippet will call the IRIS federator to figure out who has waveform data for that particular query and subsequently call the individual data centers to actually get the data. This happens fully automatically - please note that the clients also supports non-standard waveform query parameters like geographical constraints.

    >>> from obspy import UTCDateTime
    >>> client = RoutingClient("iris-federator")
    >>> st = client.get_waveforms(
    ...     channel="LHZ", starttime=UTCDateTime(2017, 1, 1),
    ...     endtime=UTCDateTime(2017, 1, 1, 0, 5), latitude=10,
    ...     longitude=10, maxradius=25)
    >>> print(st)
    2 Trace(s) in Stream:
    II.MBAR.00.LHZ | 2017-01-01T00:00:00Z - ... | 1.0 Hz, 300 samples
    II.MBAR.10.LHZ | 2017-01-01T00:00:00Z - ... | 1.0 Hz, 300 samples

The same works for stations:

    >>> client = RoutingClient("iris-federator")
    >>> inv = client.get_stations(
    ...     channel="LHZ", starttime=UTCDateTime(2017, 1, 1),
    ...     endtime=UTCDateTime(2017, 1, 1, 0, 5), latitude=10,
    ...     level="channel", longitude=10, maxradius=25)
    >>> print(inv)
    Inventory created at 2017-10-09T14:26:28.466161Z
        Created by: ObsPy 1.0.3.post0+1706.gef068de324.dirty
                    https://www.obspy.org
        Sending institution: IRIS-DMC,ObsPy ..., SeisComP3 (GFZ,IPGP, IRIS-DMC)
        Contains:
            Networks (6):
                AF, G, II, IU, TT, YY
            Stations (10):
                AF.EKNA (Ekona, Cameroon)
                AF.KIG (Kigali, Rwanda)
                G.TAM (Tamanrasset, Algeria)
                II.MBAR (Mbarara, Uganda)
                IU.KOWA (Kowa, Mali)
                TT.TATN (Station Tataouine, Tunisia)
                YY.GIDA (Health Center, Gidami, Ethiopia)
                YY.GUBA (Police Station, Guba, Ethiopia)
                YY.MEND (High School, Mendi, Ethiopia)
                YY.SHER (Police Station, Sherkole, Ethiopia)
            Channels (11):
                AF.EKNA..LHZ, AF.KIG..LHZ, G.TAM.00.LHZ, II.MBAR.00.LHZ,
                II.MBAR.10.LHZ, IU.KOWA.00.LHZ, TT.TATN.00.LHZ, YY.GIDA..LHZ,
                YY.GUBA..LHZ, YY.MEND..LHZ, YY.SHER..LHZ

Please see the documentation for each method for further information and examples.

## Classes & Functions

`client.Client` | FDSN Web service request client.
`routing.routing_client.RoutingClient` | Helper function to get the correct routing instance.

## Modules

`client` | FDSN Web service client for ObsPy.
`routing` | obspy.clients.fdsn.routing - Routing services for FDSN web services
`routing.routing_client` | Base class for all FDSN routers.
`routing.routing_client.BaseRoutingClient` |
`routing.eidaws_routing_client` | Routing client for the EIDAWS routing service.
`routing.eidaws_routing_client.EIDAWSRoutingClient` | Routing client for the EIDAWS routing service.
`routing.federator_routing_client` | Routing client for the IRIS federator routing service.
`routing.federator_routing_client.FederatorRoutingClient` |
`mass_downloader` | Mass Downloader for FDSN Compliant Web Services
`mass_downloader.domain` | Domain definitions for the download helpers.
`mass_downloader.mass_downloader.MassDownloader` | Class facilitating data acquisition across all FDSN web service
`mass_downloader.restrictions` | Non-geographical restrictions and constraints for the mass downloader.
`mass_downloader.download_helpers` | Helpers for the mass downloader.

### Thank you!

We would like to thank our contributors, whose efforts make this software what it is. These people have helped by writing code and documentation, and by testing. They have created and maintained this product, its associated libraries and applications, our build tools and our web sites.

#### Contributors

- Ackerley, Nick
- Allgeyer, Sebastien
- Ammon, Charles J.
- Antunes, Emanuel
- Arnarsson, Ólafur St.
- Bank, Markus
- Barsch, Robert
- Behr, Yannik
- Bernardi, Fabrizio
- Bernauer, Felix
- Bes de Berc, Maxime
- Beyreuther, Moritz
- Boltz, Shawn
- Bonaimé, Sébastien
- Carothers, Lloyd
- Chamberlain, Calum
- Chambers, Derrick
- Chen, Zhao
- Clark, Adam
- Danecek, Peter
- Egdorf, Sven
- Engels, Fabian
- Ermert, Laura
- Eulenfeld, Tom

- Fabbri, Tommaso
- Falco, Nicholas
- Fee, Jeremy
- Grellier, Clément
- Grunberg, Marc
- Hammer, Conny
- Heimann, Sebastian
- Heiniger, Lukas
- Hope, Gaute
- Igel, Heiner
- Inza, Adolfo
- Isken, Marius
- Ketchum, David
- Koymans, Mathijs
- Kremers, Simon
- Kress, Victor
- Krieger, Lars
- Krischer, Lion
- Kula, Damian
- Käufl, Paul
- Köhler, Andreas
- Lecocq, Thomas
- Leeman, John
- Legovini, Paride

- Lesage, Philippe
- Li, Yulin
- Lomax, Anthony
- Lopes, Rui L.
- MacCarthy, Jonathan
- Maggi, Alessia
- Martin, Henri
- Medlin, Andrew
- Megies, Tobias
- Meschede, Matthias
- Michelini, Alberto
- Miller, Nathaniel C.
- Morgenstern, Bernhard
- Nof, Ran Novitsky
- Panning, Mark P.
- Parker, Tom
- Pestourie, Romain
- Rapagnani, Giovanni
- Reyes, Celso
- Ringler, Adam
- Rothenhäusler, Nicolas
- Russo, Emiliano
- Sales de Andrade, Elliott

- Satriano, Claudio
- Saul, Joachim
- Scheingraber, Chris
- Schneider, Simon
- Sippl, Christian
- Snoke, Arthur
- Stange, Stefan
- Stähler, Simon C.
- Sullivan, Benjamin
- Tian, Dongdong
- Trabant, Chad
- Trani, Luca
- Uieda, Leonardo
- Walker, Andrew
- Walther, Marcus
- Wassermann, Joachim
- Williams, Mark C.
- Winkelman, Andrew
- Zaccarelli, Riccardo
- Zad, Seyed Kasra Hosseini
- Zhu, Lijun
- van Driel, Martin
- van Wijk, Kasper

#### Funds

ObsPy was partially funded by the

- German Science Foundation (DFG) via grant DFG IG 16/9-1
- German Ministry for Education and Research (BMBF), GEOTECHNOLOGIEN grant 03G0646H.
- NERA project (Network of European Research Infrastructures for Earthquake Risk Assessment and Mitigation) under the European Community's Seventh Framework Programme (FP7/2007-2013) grant agreement n° 262330
- Leibniz Institute for Applied Geophysics (LIAG)
- VERCE EU-FP7 project (no. 283543)