LCRA Flood Status API
A Python library and CLI tool for extracting real-time flood status, lake levels, river conditions, and floodgate operations from the Lower Colorado River Authority (LCRA) Hydromet system.
Overview
This project provides both a command-line interface and a RESTful API to access current flood status, lake levels, river conditions, and floodgate operations for the Lower Colorado River basin in Texas. It fetches data directly from LCRA's public APIs, structures it with Pydantic models, and exposes it via a modern, documented FastAPI interface.
Features
- Real-time Data: Fetches up-to-date information from LCRA's official APIs
- Structured Models: Uses Pydantic for data validation and serialization
- Multiple Endpoints: Access lake levels, river conditions, floodgate operations, and complete flood reports
- CLI Tool: Command-line interface for quick data extraction
- REST API: FastAPI-based service with interactive documentation
- Async & Fast: Built with FastAPI and httpx for high performance
- Type Safe: Full type hints and Pydantic models
- Well Tested: Comprehensive test suite with pytest
Installation
From PyPI
pip install lcra
Or using uv:
uv pip install lcra
From Source
git clone https://github.com/lancereinsmith/lcra.git
cd lcra
uv sync # or: pip install -e .
Requirements
- Python 3.10 or higher
- uv (recommended) or pip
Quick Start
CLI Usage
Extract flood operations report:
lcra get --report
Get lake levels:
lcra get --lake-levels
Save to file:
lcra get --report --save
API Server
Start the API server:
lcra serve
Then visit http://localhost:8080/docs for interactive API documentation.
Usage
Command Line Interface
The CLI provides several commands for extracting LCRA data:
Get Data
# Full flood operations report
lcra get --report
# Lake levels only
lcra get --lake-levels
# River conditions only
lcra get --river-conditions
# Floodgate operations only
lcra get --floodgate-operations
Save Output
# Auto-named timestamped file
lcra get --report --save
# Creates: reports/report_2025-01-15T10-30-45.json
# Custom filename
lcra get --report --saveas my_report
# Creates: reports/my_report.json
Start API Server
# Default (localhost:8080)
lcra serve
# Custom host and port
lcra serve --host 0.0.0.0 --port 9000
Python API
from scraper import LCRAFloodDataScraper
from lcra import FloodOperationsReport
async with LCRAFloodDataScraper() as scraper:
# Get complete report
report: FloodOperationsReport = await scraper.scrape_all_data()
# Get specific data
lake_levels = await scraper.scrape_lake_levels()
river_conditions = await scraper.scrape_river_conditions()
floodgate_operations = await scraper.scrape_floodgate_operations()
REST API Endpoints
| Endpoint | Method | Description |
|---|---|---|
/ |
GET | API root info |
/health |
GET | Health check (LCRA API connectivity) |
/flood-report |
GET | Complete flood operations report |
/lake-levels |
GET | Current lake levels at dams |
/river-conditions |
GET | Current river conditions |
/floodgate-operations |
GET | Current floodgate operations |
/docs |
GET | Swagger UI (interactive API docs) |
/redoc |
GET | ReDoc (alternative API docs) |
Example API Usage
# Get complete flood report
curl http://localhost:8080/flood-report
# Get lake levels
curl http://localhost:8080/lake-levels
# Health check
curl http://localhost:8080/health
Visit http://localhost:8080/docs for interactive API documentation.
Development
Setup
# Clone repository
git clone https://github.com/lancereinsmith/lcra.git
cd lcra
# Install with dev dependencies
uv sync --group dev
Running Tests
pytest
With coverage:
pytest --cov
Code Quality
# Format code
black .
# Lint code
ruff check .
# Type check
mypy .
Building Documentation
mkdocs serve # Local development
mkdocs build # Build static site
Project Structure
lcra/
├── src/
│ ├── api/ # FastAPI application
│ │ └── __init__.py
│ ├── scraper/ # LCRA data scraper
│ │ └── __init__.py
│ └── lcra/ # Data models and CLI
│ ├── __init__.py
│ └── cli.py # CLI entrypoint
├── tests/ # Test suite
├── docs/ # Documentation
├── pyproject.toml # Project configuration
└── README.md # This file
Data Sources
This library accesses data from the LCRA Hydromet system, which provides:
- Lake Levels: Current elevations at major dams (Buchanan, Inks, LBJ, Marble Falls, Travis, Austin, Bastrop)
- River Conditions: Stage, flow, and flood status at various gauge locations
- Floodgate Operations: Current and forecasted floodgate operations
- Narrative Summaries: Text summaries of current flood conditions
Troubleshooting
- No Data Returned: Ensure the LCRA website and APIs are accessible from your network. The
/healthendpoint will indicate if the upstream API is reachable. - Dependency Issues: Make sure you have run
uv syncand are using Python 3.10 or higher. - Port Conflicts: If port 8080 is in use, specify another port with
--port <number>. - Import Errors: Ensure the package is installed:
pip install lcraoruv pip install lcra
Contributing
Contributions are welcome! Please see CONTRIBUTING.md for guidelines.
Documentation
Full documentation is available at: https://lancereinsmith.github.io/lcra/
Or build locally:
mkdocs serve
License
MIT License - see LICENSE file for details.
Credits
- LCRA Hydromet for providing public data
- Built with FastAPI, Pydantic, and httpx
- Documentation powered by MkDocs and Material for MkDocs
Metadata
Release files for lcra 0.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| lcra-0.4.0.tar.gz | 80.9 kB | With provenance | Details for lcra-0.4.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| lcra-0.4.0-py3-none-any.whl | Python 3 | none | any | Details for lcra-0.4.0-py3-none-any.whl |
Total release size: 92.1 kB
Release files / lcra-0.4.0.tar.gz
| Download URL | lcra-0.4.0.tar.gz |
|---|---|
| Size | 80.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
953ccaa9356dd5d2ef6a6875124bceffc5e2e0fd5b4135a068c4c6399c9f7980
|
|
BLAKE2b-256 checksum How to use checksums |
b7a0b2520fded9fabd5cda9013c4827bd1c8be63fb335d2a884ffc83c52bccc2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 17, 2026.
Transparency logRelease files / lcra-0.4.0-py3-none-any.whl
| Download URL | lcra-0.4.0-py3-none-any.whl |
|---|---|
| Size | 11.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
08a90262abbe898b848056d742ff80c4607bfe0b70b40311c686a640ebc4e5fd
|
|
BLAKE2b-256 checksum How to use checksums |
63fc63ddb40d8e111915cff33f9db91c140783672e4a87574f8cda1be54d90ab
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 17, 2026.
Transparency logSecurity for lcra 0.4.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for lcra-0.4.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 17, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.