Metadata-Version: 2.4
Name: beachdayapi
Version: 0.1.5
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 36,000+ beaches across 110 countries including the US, UK, Spain, Italy, France, Croatia, Greece, Malta, Cyprus, Turkey, Portugal, Japan, Philippines, South Korea, Mexico, Costa Rica, Cuba, Dominican Republic, Puerto Rico, Jamaica, Bahamas, Panama, India, Indonesia, Norway, Sweden, Denmark, Ireland, Iceland, Albania, Montenegro, Malaysia, Sri Lanka, Taiwan, Australia, South Africa, French Polynesia, New Caledonia, Fiji, New Zealand, Cambodia, Thailand, Vietnam, China, Samoa, Tonga, Cook Islands, American Samoa, Tuvalu, Niue, Wallis and Futuna, Tokelau, Brazil, Colombia, Uruguay, Ecuador, Chile, Peru, Barbados, Maldives, all 36 African countries, and more.

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