Metadata-Version: 2.4
Name: beachdayapi
Version: 0.1.3
Summary: Python client for the Beach Day API — real-time beach and surf conditions
Author-email: Beach Day API <hello@beachdayapi.com>
License-Expression: 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: 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 5,300+ beaches across the US, Australia, South Africa, Spain, Cambodia, Thailand, Vietnam, and China.

```bash
pip install beachdayapi
```

## Quick Start

```python
from beachdayapi import BeachDayAPI

client = BeachDayAPI("bda_your_api_key")

# Search beaches by state (supports offset/limit pagination)
beaches = client.beaches.list(state="CA")
# Pagination: client.beaches.list(state="CA", offset=100, limit=50)
# Filter by country: client.beaches.list(country="Cambodia")
for b in beaches["data"]:
    print(b["name"], b["state"])

# Search beaches by name
malibu = client.beaches.list(search="Malibu")
print(f"Found {malibu['count']} beaches matching 'Malibu'")

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

# Get current conditions (supports offset/limit)
conditions = client.beaches.conditions(372)
# Pagination: client.beaches.conditions(372, offset=30, limit=15)
print(conditions["data"]["water_quality_grade"])

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

# Discover available countries
countries = client.beaches.countries()
for c in countries["results"]:
    print(f"{c['country']}: {c['beach_count']} beaches")

# 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 |
| `client.beaches.countries()` | `GET /v1/countries` | 1 credit | List countries with counts |

## 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).
