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.
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
Simple Setup (Recommended)
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
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Make your changes
- Add tests for new functionality
- Ensure all tests pass (
pytest) - Ensure type checking passes (
mypy dbhydro_py/) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 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.