API Documentation

Everything you need to integrate beach data into your application.

Base URL: https://beachdayapi.com/v1

🏖️
See it in action first? Check the live demo page — preview real beach data, the API response, and code samples without creating an account.
Live Demo →

Authentication

All API requests (except /v1/health) require authentication via Bearer token. Include your API key in the Authorization header:

Authorization: Bearer ***

Get your API key from your Dashboard after signing up. Every account gets one key by default.

If your key is compromised, you can regenerate it from the API Keys page. The old key will stop working immediately.

Base URL

https://beachdayapi.com/v1

All endpoints are relative to this base URL. HTTPS is required for all requests.

Prefer RapidAPI? You can also test and subscribe to Beach Day API on RapidAPI if you prefer marketplace billing and generated sample code. Learn more →

Credits and Rate Limits

Beach Day API uses a pre-paid credit system. Each API call deducts credits from your balance based on the endpoint accessed.

EndpointCost
GET /v1/beaches1 credit
GET /v1/beaches/{id}5 credits
GET /v1/beaches/{id}/conditions3 credits
GET /v1/beaches/scored10 credits
GET /v1/healthFree

When your credit balance reaches 0, API calls return HTTP 402 with a JSON body explaining the shortfall:

{
  "error": "insufficient_credits",
  "balance": 0,
  "required": 5,
  "message": "You need 5 credits. Purchase more at https://beachdayapi.com/credits/pricing/"
}

Purchase credit packs from the pricing page. Credits expire 1 year after purchase.

Error Codes

StatusMeaningResponse
401Unauthorized{"detail": "Invalid API key"}
402Insufficient Credits{"error": "insufficient_credits", "balance": N, "required": M}
404Not Found{"error": "not_found"}
429Rate Limited{"detail": "Request was throttled"}
500Server Error{"detail": "A server error occurred"}
GET /v1/beaches 1 credit

Search and list beaches. Supports offset/limit pagination. Filter by state or search by name with the query parameters below.

Query Parameters
ParameterTypeRequiredDescription
searchstringNoSearch beaches by name (case-insensitive, e.g. Malibu)
statestringNoState/province code (e.g. CA, FL, HI, AU-NSW, AU-VIC, AU-QLD, AU-WA, AU-SA, AU-TAS, AU-NT, ZA-WC, ZA-EC, ZA-KZN, ES-AN, ES-CT, ES-IB, IT-LIG, IT-CAM, IT-SIC, FR-BRE, FR-PAC, FR-COR, HR-18, HR-17, GR-M, GR-L, PF-SI, NC-S, FJ-W, NZ-AUK, NZ-WKO, NZ-CAN, WS, TO, CK, BR-RJ, BR-SP, BR-BA, CO-SAP, CO-ATL, UY-MO, EC-W, EC-M, CL-CE, CL-MA, PE-CE, IN-GJ, IN-MH, IN-GA, IN-KA, IN-KL, IN-TN, IN-AP, IN-OD, IN-WB, IN-AN, IN-LD, MA, DZ, TN, EG, KE, TZ, MG, MU, SC, CV, SN, GH, MZ, NA, AO, KM, LY, ER, DJ, SO, SD, MR, GN, GW, SL, LR, CI, CM, GQ, GA, CG, CD, ST, SH, ML, TG, BJ, NG)
countrystringNoFilter by country name (case-insensitive, e.g. Cambodia, Vietnam, Thailand, French Polynesia, Samoa, Tonga, New Zealand, India, Brazil, Colombia, Uruguay, Ecuador, Chile, Peru, Morocco, Algeria, Kenya, South Africa)
offsetintegerNoNumber of results to skip (default: 0). Use with limit for pagination.
limitintegerNoMax results per page (default: 100, max: 500).
Code Examples
curl -H "Authorization: Bearer ***" \
     "https://beachdayapi.com/v1/beaches?state=CA"
import requests

headers = {"Authorization": "Bearer ***"}
resp = requests.get(
    "https://beachdayapi.com/v1/beaches",
    params={"state": "CA"},
    headers=headers
)
data = resp.json()
const resp = await fetch(
  "https://beachdayapi.com/v1/beaches?state=CA",
  { headers: { "Authorization": "Bearer ***" } }
);
const data = await resp.json();
require 'net/http'
require 'json'

uri = URI("https://beachdayapi.com/v1/beaches?state=CA")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer ***"
result = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
data = JSON.parse(result.body)
req, _ := http.NewRequest("GET", "https://beachdayapi.com/v1/beaches?state=CA", nil)
req.Header.Set("Authorization", "Bearer ***")
client := &http.Client{}
resp, _ := client.Do(req)
Search by Name
curl -H "Authorization: Bearer ***" \
     "https://beachdayapi.com/v1/beaches?search=Malibu"
resp = requests.get(
    "https://beachdayapi.com/v1/beaches",
    params={"search": "Malibu"},
    headers={"Authorization": "Bearer ***"}
)
const resp = await fetch(
  "https://beachdayapi.com/v1/beaches?search=Malibu",
  { headers: { "Authorization": "Bearer ***" } }
);
Example Response
{
  "count": 47,
  "results": [
    {
      "id": 1,
      "name": "Venice Beach",
      "state": "CA",
      "latitude": 33.985,
      "longitude": -118.469,
      "nearest_buoy_id": "46025",
      "nearest_tide_station": "9410660"
    }
  ]
}
GET /v1/beaches/{id} 5 credits

Retrieve full details for a single beach by ID.

Path Parameters
ParameterTypeRequiredDescription
idintegerYesBeach ID from list endpoint
Code Examples
curl -H "Authorization: Bearer ***" \
     "https://beachdayapi.com/v1/beaches/1/"
resp = requests.get(
    "https://beachdayapi.com/v1/beaches/1/",
    headers={"Authorization": "Bearer ***"}
)
const resp = await fetch(
  "https://beachdayapi.com/v1/beaches/1/",
  { headers: { "Authorization": "Bearer ***" } }
);
GET /v1/beaches/{id}/conditions 3 credits

Get current and recent conditions for a beach: water quality, weather, ocean conditions, and tides. Supports offset/limit pagination (default: 30 results, max: 200).

Query Parameters
ParameterTypeRequiredDescription
offsetintegerNoNumber of results to skip (default: 0)
limitintegerNoMax results per page (default: 30, max: 200)
Code Examples
curl -H "Authorization: Bearer ***" \
     "https://beachdayapi.com/v1/beaches/1/conditions/"
resp = requests.get(
    "https://beachdayapi.com/v1/beaches/1/conditions/",
    headers={"Authorization": "Bearer ***"}
)
const resp = await fetch(
  "https://beachdayapi.com/v1/beaches/1/conditions/",
  { headers: { "Authorization": "Bearer ***" } }
);
Example Response
{
  "beach_id": 1,
  "count": 45,
  "results": [
    {
      "date": "2025-07-04",
      "beach_day_score": 8.5,
      "water_quality": {"grade": "A", "ecoli_cfu": 18},
      "weather": {"temp_f": 76, "wind_mph": 8, "humidity_pct": 62},
      "ocean_conditions": {"wave_height_ft": 2.5, "rip_current_risk": "low"},
      "tides": [
        {"time": "06:42", "type": "low", "height_ft": 0.3},
        {"time": "13:15", "type": "high", "height_ft": 5.1}
      ]
    }
  ]
}
GET /v1/beaches/scored 10 credits

Returns beaches ranked by their current beach day score (0-100). Supports offset/limit pagination (default: 50 results, max: 200).

Query Parameters
ParameterTypeRequiredDescription
offsetintegerNoNumber of results to skip (default: 0)
limitintegerNoMax results per page (default: 50, max: 200)
Code Examples
curl -H "Authorization: Bearer ***" \
     "https://beachdayapi.com/v1/beaches/scored/"
resp = requests.get(
    "https://beachdayapi.com/v1/beaches/scored/",
    headers={"Authorization": "Bearer ***"}
)
GET /v1/countries 1 credit

List all available countries with beach counts, ordered by count descending. Use this to discover which countries are covered, then filter by ?country= on the beaches endpoint.

Response
curl -H "Authorization: Bearer ***" https://beachdayapi.com/v1/countries

{
  "count": 58,
    "results": [
      {"country": "United States", "beach_count": 3500},
      {"country": "Spain",       "beach_count": 2488},
      {"country": "Italy",       "beach_count": 1500},
      {"country": "France",      "beach_count": 2000},
      {"country": "New Zealand", "beach_count": 698},
      {"country": "Croatia",     "beach_count": 0},
      {"country": "Greece",      "beach_count": 0},
      {"country": "French Polynesia", "beach_count": 22},
      {"country": "New Caledonia",    "beach_count": 63},
      {"country": "Fiji",             "beach_count": 18},
      {"country": "Samoa",       "beach_count": 21},
      {"country": "Tonga",       "beach_count": 12},
      {"country": "Cook Islands","beach_count": 8},
      {"country": "American Samoa","beach_count": 3},
      {"country": "Tuvalu",      "beach_count": 5},
      {"country": "Niue",        "beach_count": 3},
      {"country": "Wallis and Futuna","beach_count": 4},
      {"country": "Tokelau",     "beach_count": 1},
      {"country": "Thailand",    "beach_count": 380},
      {"country": "China",       "beach_count": 315},
      {"country": "Australia",   "beach_count": 280},
      {"country": "South Africa", "beach_count": 70},
      {"country": "Vietnam",     "beach_count": 90},
      {"country": "Cambodia",    "beach_count": 42},
      {"country": "Algeria",     "beach_count": 301},
      {"country": "Seychelles",  "beach_count": 105},
      {"country": "Comoros",     "beach_count": 107},
      {"country": "Morocco",     "beach_count": 58},
      {"country": "Egypt",       "beach_count": 45},
      {"country": "Mauritius",   "beach_count": 45},
      {"country": "Tunisia",     "beach_count": 93},
      {"country": "Cape Verde",  "beach_count": 62}
  ]
}
GET /v1/health Free

Health check endpoint. No authentication required. Returns 200 OK when the API is operational.

{"status": "ok", "service": "Beach Day API"}

Integrations & Open-Source Examples

Need help wiring this into your site?

Our team can implement Beach Day API for you, from a quick integration to a full build. Explore Implementation Services →

🐍 Python Client

Zero-dependency Python client. Install and query in two lines:

pip install beachdayapi

Usage:

from beachdayapi import BeachDayAPI

client = BeachDayAPI("bda_your_api_key")

# Search beaches
beaches = client.beaches.list(state="CA")

# Search by name
beaches = client.beaches.list(search="Malibu")

# Get scored beaches
scored = client.beaches.scored(min_score=70)

# Health check (no auth)
client.health()

PyPI · Integration page

⬡ Node.js Client

Zero-dependency Node.js client (built-in fetch, no HTTP library needed):

npm install beachdayapi

Usage:

import { BeachDayAPI } from "beachdayapi";

const client = new BeachDayAPI("bda_your_api_key");

// Search beaches
const beaches = await client.beaches.list({ state: "CA" });

// Search by name
const malibu = await client.beaches.list({ search: "Malibu" });

// Get scored beaches
const scored = await client.beaches.scored({ min_score: 70 });

// Health check (no auth)
const health = await client.health();

npm · Integration page

⚡ Zapier Integration Beta

Connect Beach Day API to Slack, Gmail, Google Sheets, and 9000+ apps via Zapier. No code required. Now in Beta — the integration has been approved and is available in the Zapier App Directory.

Available actions:

  • Look Up Beach Conditions — get current water quality, weather, ocean conditions, and tides
  • Look Up Beach Score — fetch the beach day score and grade
  • Search Beaches — find beaches by name

To use:

  1. Go to the Beach Day API page on Zapier and click Try It
  2. Use Schedule by Zapier as your trigger (for daily digests or alerts)
  3. Add a Beach Day API action and select one of the actions above
  4. Connect your Beach Day API key from your Dashboard
  5. Choose a destination (Slack, Email, Google Sheets, etc.)
# Example: daily beach conditions digest
# Trigger: Schedule by Zapier at 7am daily
# Action 1: Beach Day API → Look Up Beach Conditions
#   beach_name: "Venice Beach"
# Action 2: Send to Slack / Email / Google Sheets

Try it on Zapier → · Integration page

🔗 n8n Node

Use Beach Day API directly in your n8n workflows — search beaches, check conditions, get tides, and more.

npm install n8n-nodes-beachday

Install via Settings → Community Nodes in n8n, or find it on npm:

npm → · Integration page

🤖 Apify Actor

Run Beach Day API operations as repeatable jobs on Apify — search beaches, get beach detail, tide predictions, rules, amenities, and top scored beaches. Supports scheduled runs, webhooks, dataset exports (JSON, CSV, Excel), and AI-agent access via Apify MCP.

Available operations:

  • Search Beaches — find beaches by name, state, or country
  • Get Beach Detail — full conditions, score, rules, and amenities
  • Get Top Scored Beaches — beaches ranked by current Beach Day Score
  • Get Tide Predictions — 7-day tide data for any beach
  • Get Beach Rules — local rules (dogs, alcohol, fires, etc.)
  • Get Beach Amenities — on-site amenities (lifeguards, parking, restrooms)
  • Get Beach Conditions — historical condition snapshots

View on Apify Store → · Integration page

📘 APIDog (Interactive Docs)

Interactive API documentation with live endpoint testing, auto-generated code snippets in cURL, JavaScript, Python, and more. Browse and test every endpoint from your browser.

Open APIDog → · Integration page

🔄 Apyhub Marketplace

Browse and test Beach Day API endpoints on Apyhub with an interactive playground. Each endpoint has a live try-it console — no code required for first evaluation.

Available endpoints on Apyhub:

  • List Countries — available countries with beach counts
  • Search Beaches — find beaches by name, state, or country
  • Get Beach Detail — full conditions, score, rules, and amenities
  • Get Beach Conditions — time-based historical condition snapshots
  • Get Tide Predictions — 7-day tide data for any beach
  • Get Beach Rules — local rules (dogs, alcohol, fires, etc.)
  • Get Beach Amenities — on-site amenities (lifeguards, parking, restrooms)
  • Get Top Scored Beaches — beaches ranked by current Beach Day Score

View on Apyhub → · Integration page

🏠 Home Assistant Integration

Monitor Beach Day API conditions in Home Assistant with the community HACS integration. Add beach score, air temperature, and water temperature sensors to dashboards and automations.

Community integration, pending HACS review.

View on GitHub → · Integration page

🛒 API.market

Discover and evaluate Beach Day API through API.market, with marketplace access for teams that prefer marketplace procurement and billing.

View on API.market → · Integration page

Want another language? The Beach Day API is plain REST/JSON. You can use any HTTP client. Community-contributed client libraries for Go, Ruby, and PHP are welcome. Get in touch →

Model Context Protocol (MCP)

Connect an MCP-compatible AI assistant to Beach Day API through Streamable HTTP. MCP uses the same API keys and credit balance as the REST API.

Endpoint
https://beachdayapi.com/mcp

Send your Beach Day API key as an HTTP Bearer token:

Authorization: Bearer YOUR_API_KEY

Available read-only tools:

  • get_account_status (0 credits, account balance and active packages)
  • list_countries (1 credit)
  • search_beaches (1 credit)
  • get_beach (5 credits)
  • get_weather (3 credits)
  • get_water_quality (3 credits)
  • find_swimmable_beaches (10 credits)

Keep your API key private. MCP calls use the same credit balance as direct API requests. Manage keys from your Dashboard.