Beach Day API — Node.js Client

Client library for the Beach Day API.

npm install beachdayapi

Usage

import { BeachDayAPI } from "beachdayapi";

const client = new BeachDayAPI("bda_your_api_key");

// Search beaches by state (supports offset/limit pagination)
const beaches = await client.beaches.list({ state: "CA" });
// Pagination: client.beaches.list({ state: "CA", offset: 100, limit: 50 })
// Filter by country: client.beaches.list({ country: "Cambodia" })
// Or: client.beaches.list({ country: "Italy" })

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

// Get beach detail
const beach = await client.beaches.get(372);

// Get current conditions (supports offset/limit)
const conditions = await client.beaches.conditions(372);
// Pagination: client.beaches.conditions(372, { offset: 30, limit: 15 })

// Get scored beaches (supports offset/limit)
const scored = await client.beaches.scored({ min_score: 70 });
// Pagination: client.beaches.scored({ offset: 50, limit: 25 })

// Discover available countries
const countries = await client.beaches.countries();

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

API Key

Sign up at beachdayapi.com to get your API key. You can also set the BEACHDAY_API_KEY environment variable.

Error Handling

import {
  BeachDayAPI,
  AuthenticationError,
  InsufficientCreditsError,
  NotFoundError,
} from "beachdayapi";

try {
  await client.beaches.get(999999);
} catch (err) {
  if (err instanceof NotFoundError) {
    console.log("Beach not found");
  }
}

Requirements

• Node.js 18+ (uses built-in fetch)
• No dependencies

License

MIT