# KBWS

FDSN Web Services for CSS-like SQL Databases

---

KBWS connects your CSS-like SQL database (CSS 3.0, KB Core) to the FDSN Web Services standard.

**Leverage standard protocols for seismological data access**  
Use any FDSN-WS or REST API client (like ObsPy or [Restish](https://rest.sh)) as the interface with your database, instead of using SQL on a connected server or some other programmatic interface (like Pisces) directly.
Clients like the [ObsPy FDSN Client](https://docs.obspy.org/packages/obspy.clients.fdsn.html), `curl`, or just your web browser become viable ways to acquire data, no home-grown software installations required!

**Built on modern, open-source technologies**  
KBWS uses [FastAPI](https://fastapi.tiangolo.com/), [Pisces](https://github.com/LANL-Seismoacoustics/pisces), [SQLAlchemy](http://www.sqlalchemy.org), and [ObsPy](http://www.obspy.org) to provide a fast, standards-compliant web service layer over your existing database infrastructure.

**Flexible deployment options**  
Run KBWS natively with Pixi/pip, or deploy it in containers using Docker or Podman. Configure database schemas, waveform directories, and only the table mappings needed by each service through a simple environment file.


## Service support

KBWS currently provides usable FDSN-style services for:

* **fdsnws-event**: query and retrieve event catalogs in QuakeML, JSON, SQL debug output, or CSS origin rows.
* **fdsnws-dataselect**: retrieve waveform data in MiniSEED or SAC ZIP, plus SQL debug output or CSS Wfdisc rows.

**Station** and **Availability** services are also available when their configured database tables are present. Requests return a useful `503` response listing missing tables when a deployment cannot support a service or requested detail level.

See [Access Control](authentication.md) for the deployment-scoped security model.

## Features

* Direct integration with [ObsPy](http://www.obspy.org) FDSN client
* Support for Oracle databases via the `oracledb` driver
* Flexible schema mapping - configure any table names via environment variables
* Geographic and temporal filtering using native SQL queries
* Container-ready with rootless Podman support


## Quick Start

### Start the server

`uvicorn kbws.main:app --host 0.0.0.0 --port 8000`

### Using ObsPy

```python
from obspy.clients.fdsn import Client

# Connect to your KBWS instance
client = Client('http://localhost:8000', _discover_services=False)

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

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

See the [Usage guide](usage.md) for `curl`, Restish, and SSH port-forwarding examples.

```{toctree}
:hidden: true

installation.md
usage.md
deployment.md
authentication.md
development.md
```

```{toctree}
:hidden: true
:caption: Reference

about/changelog.md
about/license.md
API Documentation <api/modules.rst>
```
