Metadata-Version: 2.4
Name: beachdayapi
Version: 0.1.0
Summary: Python client for the Beach Day API — real-time beach and surf conditions
Author-email: Beach Day API <hello@beachdayapi.com>
License: MIT
Project-URL: Homepage, https://beachdayapi.com
Project-URL: Documentation, https://beachdayapi.com/docs
Project-URL: Repository, https://github.com/rv888/beachdayapi
Project-URL: Issues, https://github.com/rv888/beachdayapi/issues
Keywords: beach,surf,water-quality,weather,api
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# Beach Day API — Python Client

[![PyPI version](https://img.shields.io/pypi/v/beachdayapi.svg)](https://pypi.org/project/beachdayapi/)
[![Python](https://img.shields.io/pypi/pyversions/beachdayapi.svg)](https://pypi.org/project/beachdayapi/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Python client for the [Beach Day API](https://beachdayapi.com) — water quality, weather, tides, ocean conditions, beach rules, amenities, and composite scoring in a single call. Covers 1,900+ beaches across the US and Australia.

```bash
pip install beachdayapi
```

## Quick Start

```python
from beachdayapi import BeachDayAPI

client = BeachDayAPI("bda_your_api_key")

# Search beaches in California
beaches = client.beaches.list(state="CA")
for b in beaches["data"]:
    print(b["name"], b["state"])

# Get full detail for a beach
beach = client.beaches.get(372)
print(beach["data"]["name"], beach["data"]["beach_day_score"])

# Get current conditions
conditions = client.beaches.conditions(372)
print(conditions["data"]["water_quality_grade"])

# Get top-scored beaches
scored = client.beaches.scored(min_score=70, limit=10)
for b in scored["data"]:
    print(f"{b['name']}: {b['beach_day_score']}")

# Health check (no API key needed)
health = client.health()
print(health)
```

## API Key

Sign up at [beachdayapi.com](https://beachdayapi.com) to get your free API key (50 free credits, no credit card). Your key starts with `bda_`.

You can also set the `BEACHDAY_API_KEY` environment variable:

```python
import os
from beachdayapi import BeachDayAPI

client = BeachDayAPI(os.environ["BEACHDAY_API_KEY"])
```

## Endpoints

| Method | Endpoint | Cost | Description |
|---|---|---|---|
| `client.health()` | `GET /v1/health` | Free | API health check |
| `client.beaches.list()` | `GET /v1/beaches` | 1 credit | Search beaches |
| `client.beaches.get(id)` | `GET /v1/beaches/{id}` | 5 credits | Beach detail |
| `client.beaches.conditions(id)` | `GET /v1/beaches/{id}/conditions` | 3 credits | Current conditions |
| `client.beaches.scored()` | `GET /v1/beaches/scored` | 10 credits | Scored beaches |

## Error Handling

```python
from beachdayapi import (
    BeachDayAPI,
    AuthenticationError,
    InsufficientCreditsError,
    NotFoundError,
    RateLimitError,
    ServerError,
)

client = BeachDayAPI("bda_invalid_key")

try:
    client.beaches.list(state="CA")
except AuthenticationError:
    print("Check your API key")
except InsufficientCreditsError:
    print("Buy more credits at beachdayapi.com/credits/pricing/")
except RateLimitError:
    print("Slow down")
```

## Requirements

- Python 3.9+
- Zero dependencies (stdlib only)

## License

MIT — see the main [Beach Day API repository](https://github.com/rv888/beachdayapi).
