Have a CSS-like SQL database (CSS 3.0, KB Core), and wish it had an FDSN Web Services endpoint? This package uses FastAPI and Pisces to provide a FDSN-WS on your CSS database.
KBWS provides FDSN-style Event, Dataselect, Station, and Availability services
when the tables required by each service are configured. Requests for unavailable
services or unsupported detail levels return 503 with the missing table names.
KBWS uses deployment-scoped access control: it does not implement in-app user
authentication or FDSN queryauth semantics. For general client compatibility,
The Swagger UI is served at the canonical /fdsnws path. KBWS exposes
/fdsnws/dataselect/1/queryauth as an alias of the existing query
implementation; it is not separately backed and does not provide a second
authorization system. Deploy each instance with appropriately restricted network
visibility, a least-privileged read-only Oracle service identity, and waveform
filesystem mounts matching the data it may serve. Oracle Wallets are an optional
deployment choice; local users may use a normal configured database_url against
their own tables.
With KBWS, you can use any FDSN-WS or rest API client (like ObsPy or Restish) 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, curl, or just your web browser become viable ways to acquire data, no home-grown software installations required!
Requirements:
- FastAPI
- ObsPY
- SQLAlchemy
- Pisces
- python-dotenv
- The
oracledbdriver for Oracle databases - Uvicorn (async web server used by FastAPI)
...directly from the repository
pixi install
pixi shellRequirements:
- Python 3.10 or later
- Access to an Oracle database with a CSS-like schema (CSS 3.0 or KB Core)
- Oracle Instant Client for Oracle database connections
For a runtime installation, create and activate a virtual environment, then install KBWS and its dependencies directly from GitHub:
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
python -m pip install --upgrade pip
python -m pip install "kbws @ git+https://github.com/LANL-Seismoacoustics/kbws.git"
python -m pip install oracledbPisces is currently installed from its GitHub main branch:
python -m pip install git+https://github.com/LANL-Seismoacoustics/pisces.git@mainIf oracledb cannot auto-detect Oracle Instant Client, set
oracle_client_lib_dir in .env. See the configuration
section for the required database and table settings.
KBWS can also be run from a pre-built container image. See the Deployment guide for container usage with Docker and Podman.
kbws needs to know where your database is and what tables to use, so these are supplied in a small .env text file that python-dotenv uses to inject variables into your environment at runtime.
KBWS uses these configurations to target FDSN-WS requests to the right database and tables.
Write a file named .env like the following:
# .env
database_url=oracle://username:password@mydbserver.com:1523/dbname
affiliation=myowner.affiliation
arrival=myowner.arrival
assoc=myowner.assoc
# amplitude=myowner.amplitude # unused by current KBWS services
# gregion=myowner.gregion # unused by current KBWS services
# origerr=myowner.origerr # unused by current KBWS services
# remark=myowner.remark # unused by current KBWS services
# sregion=myowner.sregion # unused by current KBWS services
# stamag=myowner.stamag # unused by current KBWS services
# wftag=myowner.wftag # unused by current KBWS services
event=myowner.event
instrument=myowner.instrument
netmag=myowner.netmag
network=myowner.network
origin=myowner.origin
sensor=myowner.sensor
site=myowner.site
sitechan=myowner.sitechan
wfdisc=myowner.wfdisc
See the Usage guide for command-line access with
curl and Restish, ObsPy examples, and SSH port forwarding.
Using Pixi:
git clone https://github.com/LANL-Seismoacoustics/kbws.git
cd kbws
pixi install
pixi shellUsing containers: see the Deployment guide for development with hot reload.
- Containerize the whole KBWS web app, starting from Oracle Linux Instantclient images.
- This would allow mounting local database client configurations (e.g.
$ORACLE_HOME/network/admin) into the container. - Follow the FastAPI containerization docs.
- This would allow mounting local database client configurations (e.g.
- Parameterize the container to allow different core table names
- Move all injected dependencies (e.g.
get_db) to adependencies.py, so FastAPI can properly cache them. - [-] Implement HTTPS that can use containers and .env files, point to .pem/.key/.crt files on host machine.
- Move
Enumparameters toLiteral[...]where they enums aren't reused. - Move SwaggerUI to
/docs - Serve a static protomaps/pmtiles map page at
/ - Plan ahead for versioning by moving endpoints to
api/v1/endpoints?
O5044 "KBWS: KB Core Web Services"
© 2026. Triad National Security, LLC. All rights reserved.
This program was produced under U.S. Government contract 89233218CNA000001 for Los Alamos National Laboratory (LANL), which is operated by Triad National Security, LLC for the U.S. Department of Energy/National Nuclear Security Administration. All rights in the program are reserved by Triad National Security, LLC, and the U.S. Department of Energy/National Nuclear Security Administration. The Government is granted for itself and others acting on its behalf a nonexclusive, paid-up, irrevocable worldwide license in this material to reproduce, prepare derivative works, distribute copies to the public, perform publicly and display publicly, and to permit others to do so.