Skip to main content

DBHydro-py

A Python client library for accessing the South Florida Water Management District's DBHydro API. Retrieve water level, flow, rainfall, and other environmental data with a simple, intuitive interface.

Python 3.10+ License: MIT Type Checking: mypy

Features

  • Simple API: Intuitive methods for common data retrieval tasks
  • Multiple Endpoints: Support for time series, daily data, real-time data, aggregates, interpolation, synchronization, NEXRAD, and more
  • Flexible Date Handling: Multiple date format support with automatic parsing
  • Type Safe: Full type hints for excellent IDE support and error prevention
  • Pandas Integration: Optional DataFrame conversion for data analysis
  • Robust Error Handling: Comprehensive error reporting and validation
  • Production Ready: Extensive test coverage and strict type checking

Installation

pip install dbhydro-py

Optional Dependencies

For DataFrame functionality (recommended for data analysis):

pip install dbhydro-py[pandas]

For development:

pip install dbhydro-py[dev]

Quick Start

from dbhydro_py import DbHydroApi

# Initialize the API client
client = DbHydroApi.with_default_adapter(
    client_id="your_client_id",
    client_secret="your_client_secret"
)

# Get time series data
response = client.get_time_series(
    site_ids=['S79-E'],
    date_start='2023-01-01',
    date_end='2023-01-31'
)

# Access the data
for ts in response.time_series:
    print(f"Site: {ts.source_info.site_name}")
    for value in ts.values:
        print(f"  {value.date_time}: {value.value}")

# Convert to DataFrame (requires pandas)
df = response.to_dataframe()
print(df.head())

Custom REST Adapter

If you need to customize the HTTP client behavior:

from dbhydro_py import DbHydroApi, RestAdapterRequests

# Initialize with custom adapter
client = DbHydroApi(
    rest_adapter=RestAdapterRequests(),
    client_id="your_client_id",
    client_secret="your_client_secret"
)

# Usage is identical to the simple setup
response = client.get_time_series(site_ids=['S79-E'], ...)

API Credentials

To use the DBHydro API, you need credentials from the South Florida Water Management District. Contact SFWMD to request API access and obtain your client_id and client_secret.

Supported Endpoints

Time Series Data

# Basic time series
response = client.get_time_series(
    site_ids=['S79-E', 'S308-C'],
    date_start='2023-01-01',
    date_end='2023-01-31'
)

# With aggregation
response = client.get_time_series(
    site_ids=['S79-E'],
    date_start='2023-01-01',
    date_end='2023-12-31',
    calculation='MEAN',
    timespan_unit='MONTH'
)

Daily Data

response = client.get_daily_data(
    identifiers=['S79-E'],
    identifier_type='station',
    date_start='2023-01-01',
    date_end='2023-01-31',
    requested_datum='NAVD88'
)

Real-Time Data

response = client.get_real_time(
    identifiers=['S79-E'],
    identifier_type='sites',
    status='A'  # Active only
)

Aggregate Statistics

response = client.get_aggregate(
    station_id='S79-E',
    date_start='2023-01-01',
    date_end='2023-12-31',
    calculation='MAX',
    timespan_unit='DAY'
)

Interpolated Values

response = client.get_interpolate(
    station_id='S79-E',
    date_time='2023-06-15 12:00:00'
)

NEXRAD Precipitation Data

# Pixel data
response = client.get_nexrad_pixel_data(
    pixel_ids=['12345'],
    date_start='2023-01-01',
    date_end='2023-01-31',
    frequency='D'
)

# Polygon data
response = client.get_nexrad_polygon_data(
    identifiers=['WCA1'],
    identifier_type='polygonName',
    polygon_type=1,
    date_start='2023-01-01',
    date_end='2023-01-31',
    frequency='D'
)

Synchronized Data

response = client.get_synchronize(
    time_series_names=['S79-E', 'S308-C'],
    date_start='2023-01-01',
    date_end='2023-01-31',
    requested_datum='NAVD88'
)

Date Format Support

The library accepts multiple date formats:

# String formats
'2023-01-01'                    # Date only
'2023-01-01 12:30'             # Date and time
'2023-01-01T12:30'             # ISO format
'2023-01-0112:30:45:123'       # Full precision

# Python datetime objects
from datetime import datetime
dt = datetime(2023, 1, 1, 12, 30)
client.get_time_series(site_ids=['S79-E'], date_start=dt, date_end='2023-01-31')

Data Analysis with Pandas

# Convert any response to DataFrame
df = response.to_dataframe()

# Include metadata
df = response.to_dataframe(include_metadata=True)

# Response-specific methods
site_codes = response.get_site_codes()
latest_values = response.get_latest_values()
date_range = response.get_date_range()

Error Handling

from dbhydro_py import DbHydroException

try:
    response = client.get_time_series(
        site_ids=['INVALID-SITE'],
        date_start='2023-01-01',
        date_end='2023-01-31'
    )
except DbHydroException as e:
    print(f"API Error: {e.message}")
    print(f"HTTP Status: {e.http_status_code}")
    if e.api_status_code:
        print(f"API Status: {e.api_status_code}")

Configuration

Custom REST Adapter

from dbhydro_py.rest_adapters import RestAdapterBase

class CustomRestAdapter(RestAdapterBase):
    def get(self, endpoint: str, params: dict):
        # Your custom implementation
        pass

client = DbHydroApi(
    rest_adapter=CustomRestAdapter(),
    client_id="your_client_id", 
    client_secret="your_client_secret"
)

API Versioning

# Use a specific API version
client = DbHydroApi(
    rest_adapter=RestAdapterRequests(),
    client_id="your_client_id",
    client_secret="your_client_secret",
    api_version=2  # Default is 1
)

Testing

The library includes comprehensive tests. See TESTING.md for details on running tests and contributing.

# Run all tests
pytest

# Run with coverage
pytest --cov=dbhydro_py

# Type checking
mypy dbhydro_py/

Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Make your changes
  4. Add tests for new functionality
  5. Ensure all tests pass (pytest)
  6. Ensure type checking passes (mypy dbhydro_py/)
  7. Commit your changes (git commit -m 'Add amazing feature')
  8. Push to the branch (git push origin feature/amazing-feature)
  9. Open a Pull Request

Requirements

  • Python 3.10+
  • requests >= 2.25.0
  • pandas >= 1.3.0 (optional, for DataFrame functionality)

License

This project is licensed under the MIT License - see the LICENSE file for details.


Note: This is an unofficial client library. For official API documentation and support, please contact the South Florida Water Management District.

Metadata

Release files for dbhydro-py 0.0.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for dbhydro-py 0.0.1
File Size Uploaded Provenance Actions
dbhydro_py-0.0.1.tar.gz 48.7 kB With provenance Details for dbhydro_py-0.0.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for dbhydro-py 0.0.1
File Interpreter ABI Platform Actions
dbhydro_py-0.0.1-py3-none-any.whl Python 3 none any Details for dbhydro_py-0.0.1-py3-none-any.whl

Total release size: 87.9 kB

Release files / dbhydro_py-0.0.1.tar.gz

Download URL dbhydro_py-0.0.1.tar.gz
Size 48.7 kB
Tags Source
SHA-256 checksum
How to use checksums
b1133f232d21df6552b1e7cd377760f5f6f03eddd6efec83c44de2bead183ea0
BLAKE2b-256 checksum
How to use checksums
924b77d4eeb8157920b72eb810f8f784063186a2199188a3f09f719c2d88fbff
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

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 Feb 3, 2026.

Transparency log

Release files / dbhydro_py-0.0.1-py3-none-any.whl

Download URL dbhydro_py-0.0.1-py3-none-any.whl
Size 39.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
387298f17d26bd7843c745e301a87a2f9e24c36d64fa24d64e0bcf4c72781f19
BLAKE2b-256 checksum
How to use checksums
a8ac29dd91a7599a0ac49b4a00ddcc66ad1d160d2a2dde8dce790cc6eb73a59e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

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 Feb 3, 2026.

Transparency log

Security for dbhydro-py 0.0.1

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 dbhydro_py-0.0.1.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 Feb 3, 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.

Release history Release notifications | RSS feed

This release

0.0.1 This release

2 release files Full provenance

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