Beach Day API — Python Client

Python client for the Beach Day API — 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.

pip install beachdayapi

Quick Start

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 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:

import os
from beachdayapi import BeachDayAPI

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

Endpoints

Error Handling

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.