Skip to main content

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.

Python 3.10+ License: MIT

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 /health endpoint will indicate if the upstream API is reachable.
  • Dependency Issues: Make sure you have run uv sync and 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 lcra or uv 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

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)

Source distribution for lcra 0.4.0
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)

Table of built distributions (wheels) for lcra 0.4.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page