Usage#

KBWS exposes FDSN Web Services over HTTP. Command-line tools, Python clients, and other FDSN-compatible applications can query events and waveforms from a running KBWS instance.

The examples below assume the service is available at http://localhost:8000.

Using ObsPy#

Use ObsPy’s FDSN client for event and waveform queries. Set _discover_services=False because KBWS does not provide all of the service discovery metadata expected by ObsPy.

from obspy.clients.fdsn import Client

client = Client("http://localhost:8000", _discover_services=False)

catalog = client.get_events(
    starttime="2012-11-01",
    endtime="2012-11-03",
    minlatitude=40,
    maxlatitude=47,
)

stream = client.get_waveforms(
    network="IU",
    station="ANMO",
    location="00",
    channel="BH?",
    starttime="2012-11-01T00:00:00",
    endtime="2012-11-01T01:00:00",
)

For a deployment protected by HTTP Digest authentication, pass the deployment credentials to the ObsPy client:

from obspy.clients.fdsn import Client

client = Client(
    "https://data.example.org",
    user="USERNAME",
    password="PASSWORD",
    _discover_services=False,
)

ObsPy and local certificate stores#

When a deployment certificate is trusted by the operating system but not by Python’s default CA bundle, ObsPy clients may need the truststore package. This can occur with macOS system keychains. Inject the system trust store before importing or using ObsPy:

import truststore
truststore.inject_into_ssl()

from obspy.clients.fdsn import Client

Install truststore in the same environment as ObsPy. This is preferable to disabling TLS certificate verification. A deployment may instead provide its CA bundle through the normal Python/OpenSSL configuration.

Using curl#

KBWS endpoints can also be queried directly with curl:

# Get events as QuakeML
curl "http://localhost:8000/fdsnws/event/1/query?starttime=2012-11-01&endtime=2012-11-03&minlatitude=40&maxlatitude=47"

# Get waveforms as MiniSEED
curl "http://localhost:8000/fdsnws/dataselect/1/query?net=IU&sta=ANMO&loc=00&cha=BHZ&start=2012-11-01T00:00:00&end=2012-11-01T01:00:00" -o data.mseed

For HTTP Digest authentication, use curl’s --digest option and credentials from the deployment:

curl --digest -u 'USERNAME:PASSWORD' \\
  "https://data.example.org/fdsnws/event/1/query?starttime=2012-11-01" \\
  -o events.xml

Using Restish#

Restish can consume the KBWS OpenAPI description and provide an FDSN-oriented command-line interface. After installing Restish, configure and synchronize an endpoint:

restish api configure kbws http://localhost:8000
restish api sync kbws

For a Digest-protected deployment, provide the credentials when invoking Restish (or configure them using the equivalent Restish authentication prompt):

restish --auth 'USERNAME:PASSWORD' kbws event-query --starttime 2012-11-01

For example, query events and save the QuakeML response:

restish kbws event-query \
  --starttime 2012-11-01 \
  --endtime 2012-11-03T01:00:00.00 \
  --minlatitude 40 \
  --maxlatitude 47 \
  --minlongitude -10 \
  --maxlongitude 5 \
  --mindepth 1.3 \
  --maxdepth 100 > quakes.xml

Access through an SSH tunnel#

If the server is not directly reachable as a web server, forward its KBWS port to your local machine with SSH. For example, if KBWS listens on port 8000 on myserver.example.org:

ssh -L 8000:localhost:8000 myserver.example.org

Then use http://localhost:8000 with curl, Restish, or ObsPy. The server must also have the waveform directories mounted at the same paths recorded in its database; otherwise waveform queries can succeed while waveform reads fail.