obspy-fdsn-earthquake

name	obspy-fdsn-earthquake
description	Plan, clarify, and implement earthquake data downloads with ObsPy FDSN clients. Use when Codex needs to help download seismic event catalogs, station metadata, waveform MiniSEED, response metadata, or bulk/mass downloads from FDSN web services using ObsPy, including requests involving get_events, get_stations, get_waveforms, get_waveforms_bulk, RoutingClient, or MassDownloader.

ObsPy FDSN Earthquake

Workflow

Translate the user's request into a reproducible download plan before writing code or running downloads.

1. Identify the target data:
   • events: earthquake catalog metadata, usually QuakeML or text/CSV export.
   • stations: network/station/channel metadata, usually StationXML.
   • waveforms: waveform time series, usually MiniSEED.
   • responses: instrument response, usually included through station level="response" or downloaded beside waveforms.
2. Extract constraints from the user request:
   • time window, event origin time, pre-event and post-event padding
   • geographic box or radius, or event-centric station radius
   • magnitude, depth, catalog/provider, event id if known
   • network, station, location, channel codes, and sampling/channel family such as BH?, HH?, LH?
   • output directory, naming convention, file formats, and whether to attach/remove response
3. Ask only for missing values that would change the query. Make conservative defaults explicit when proceeding:
   • provider: EARTHSCOPE for global/event examples, USGS for event catalog only, EIDA/eida-routing for European stations, or the provider named by the user
   • waveform padding: 60 seconds before to 10 minutes after an event for a small example, but confirm for research downloads
   • station metadata level: response when the workflow may need instrument correction, otherwise channel
4. Choose the ObsPy interface:
   • Use Client(...) for a known provider and ordinary event/station/waveform requests.
   • Use RoutingClient("earthscope-federator") or RoutingClient("eida-routing") when the user wants cross-datacenter waveform/station discovery or provides only geographic constraints.
   • Use MassDownloader when the request spans many stations, long windows, or needs robust local waveform/station storage.
5. Produce runnable Python with clear parameters at the top, deterministic output paths, and basic error handling for empty catalogs, missing stations, and unavailable waveform segments.

ObsPy Patterns

Use UTCDateTime for all FDSN times.

Small event catalog query:

from obspy import UTCDateTime
from obspy.clients.fdsn import Client

client = Client("USGS")
catalog = client.get_events(
    starttime=UTCDateTime("2024-01-01"),
    endtime=UTCDateTime("2024-02-01"),
    minmagnitude=6.0,
)
catalog.write("events.xml", format="QUAKEML")

Known station waveform and response:

from obspy import UTCDateTime
from obspy.clients.fdsn import Client

client = Client("EARTHSCOPE")
t0 = UTCDateTime("2010-02-27T06:45:00")
t1 = t0 + 60 * 60

stream = client.get_waveforms("IU", "ANMO", "00", "LHZ", t0, t1)
inventory = client.get_stations(
    network="IU", station="ANMO", location="00", channel="LHZ",
    starttime=t0, endtime=t1, level="response"
)

stream.write("IU.ANMO.00.LHZ.mseed", format="MSEED")
inventory.write("IU.ANMO.00.LHZ.xml", format="STATIONXML")

Bulk waveform requests:

bulk = [
    ("IU", "ANMO", "00", "BH?", t0, t1),
    ("IU", "COLA", "00", "BH?", t0, t1),
]
stream = client.get_waveforms_bulk(bulk)
stream.write("waveforms.mseed", format="MSEED")

Routing client for geographic discovery:

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

client = RoutingClient("earthscope-federator")
stream = client.get_waveforms(
    channel="LHZ",
    starttime=UTCDateTime("2017-01-01"),
    endtime=UTCDateTime("2017-01-01T00:05:00"),
    latitude=10,
    longitude=10,
    maxradius=25,
)

For large downloads, read references/obspy-fdsn-download-guide.md before writing the final script.

Quality Checks

Before handing off a script or result:

• Print the selected provider, time window, event count, station/channel count, and waveform trace count.
• Save event catalogs as QuakeML, station metadata as StationXML, and waveforms as MiniSEED unless the user asks otherwise.
• Keep raw downloads separate from processed outputs.
• Avoid silent broad queries. If a wildcard request can become very large, add explicit limits or ask for confirmation.
• Note that FDSN availability varies by provider; handle FDSNNoDataException as a normal outcome for individual station/channel requests.

Source

This skill is based on the official ObsPy FDSN client documentation: https://docs.obspy.org/packages/obspy.clients.fdsn.html