beachdayapi 0.1.4

Python client for the Beach Day API — real-time beach and surf conditions

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 5,300+ beaches across the US, Australia, South Africa, Spain, Cambodia, Thailand, Vietnam, and China.

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

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

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.