Documentación de la API

Autenticación

Todas las solicitudes API (excepto /v1/health) requieren autenticación mediante token Bearer. Incluye tu clave API en el encabezado Authorization:

Authorization: Bearer ***

Obtén tu clave API desde tu Panel después de registrarte. Cada cuenta recibe una clave por defecto.

Si tu clave está comprometida, puedes regenerarla desde la página de Claves API. La clave anterior dejará de funcionar inmediatamente.

URL Base

https://beachdayapi.com/v1

Todos los endpoints son relativos a esta URL base. HTTPS es obligatorio para todas las solicitudes.

¿Prefieres RapidAPI? También puedes probar y suscribirte a Beach Day API en RapidAPI si prefieres facturación de marketplace y código de ejemplo generado. Más información →

Créditos y Límites de Velocidad

Beach Day API utiliza un sistema de créditos prepagados. Cada llamada API deduce créditos de tu saldo según el endpoint consultado.

Endpoint	Costo
`GET /v1/beaches`	1 credit
`GET /v1/beaches/{id}`	5 credits
`GET /v1/beaches/{id}/conditions`	3 credits
`GET /v1/beaches/scored`	10 credits
`GET /v1/health`	Gratis

Cuando tu saldo de créditos llega a 0, las llamadas API retornan HTTP 402 con un cuerpo JSON explicando el déficit:

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

Compra paquetes de créditos desde la página de precios. Los créditos caducan 1 año después de la compra.

Códigos de Error

Estado	Significado	Respuesta
`401`	No Autorizado	`{"detail": "Invalid API key"}`
`402`	Créditos Insuficientes	`{"error": "insufficient_credits", "balance": N, "required": M}`
`404`	No Encontrado	`{"error": "not_found"}`
`429`	Límite de Velocidad	`{"detail": "Request was throttled"}`
`500`	Error del Servidor	`{"detail": "A server error occurred"}`

GET /v1/beaches 1 credit

Busca y lista playas. Admite paginación offset/limit. Filtra por estado o busca por nombre con los parámetros de consulta a continuación.

Parámetros de Consulta

Parámetro	Tipo	Requerido	Descripción
`search`	string	No	Buscar playas por nombre (sin distinción de mayúsculas, ej. `Malibu`)
`state`	string	No	Código de estado/provincia (ej. 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)
`country`	string	No	Filtra por nombre de país (sin distinción de mayúsculas, ej. `Camboya`, `Vietnam`, `Tailandia`, `Polinesia Francesa`, `Samoa`, `Tonga`, `Nueva Zelanda`, `India`, `Brasil`, `Colombia`, `Uruguay`, `Ecuador`, `Chile`, `Perú`, `Marruecos`, `Argelia`, `Kenia`, `Sudáfrica`)
`offset`	integer	No	Número de resultados a omitir (predeterminado: 0). Usar con `limit` para paginación.
`limit`	integer	No	Resultados máximos por página (predeterminado: 100, máx: 500).

Ejemplos de Código

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)

Búsqueda por Nombre

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 ***" } }
);

Respuesta de Ejemplo

{
  "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

Obtén detalles completos de una playa por su ID.

Parámetros de Ruta

Parámetro	Tipo	Requerido	Descripción
`id`	integer	Sí	ID de playa del endpoint de listado

Ejemplos de Código

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

Obtén condiciones actuales y recientes de una playa: calidad del agua, clima, condiciones oceánicas y mareas. Admite paginación offset/limit (predeterminado: 30 resultados, máx: 200).

Parámetros de Consulta

Parámetro	Tipo	Requerido	Descripción
`offset`	integer	No	Número de resultados a omitir (predeterminado: 0)
`limit`	integer	No	Resultados máximos por página (predeterminado: 30, máx: 200)

Ejemplos de Código

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 ***" } }
);

Respuesta de Ejemplo

{
  "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

Devuelve playas ordenadas por su puntuación actual de Beach Day Score (0-100). Admite paginación offset/limit (predeterminado: 50 resultados, máx: 200).

Parámetros de Consulta

Parámetro	Tipo	Requerido	Descripción
`offset`	integer	No	Número de resultados a omitir (predeterminado: 0)
`limit`	integer	No	Resultados máximos por página (predeterminado: 50, máx: 200)

Ejemplos de Código

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

Lista todos los países disponibles con conteo de playas, ordenados por conteo descendente. Úsalo para descubrir qué países están cubiertos y luego filtra con ?country= en el endpoint de playas.

Respuesta

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 Gratis

Endpoint de verificación de salud. No requiere autenticación. Retorna 200 OK cuando la API está operativa.

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

Integraciones y Ejemplos de Código Abierto

¿Necesitas ayuda para conectarlo a tu sitio?

Nuestro equipo puede implementar Beach Day API por ti, desde una integración rápida hasta un desarrollo completo. Explorar los Servicios de Implementación →

🐍 Cliente Python

Cliente Python sin dependencias. Instala y consulta en dos líneas:

pip install beachdayapi

Uso:

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 · Página de integración

⬡ Cliente Node.js

Cliente Node.js sin dependencias (fetch integrado, sin biblioteca HTTP):

npm install beachdayapi

Uso:

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 · Página de integración

⚡ Integración Zapier Beta

Conecta Beach Day API a Slack, Gmail, Google Sheets y más de 9000 apps mediante Zapier. Sin necesidad de código. Ahora en Beta — la integración ha sido aprobada y está disponible en el Directorio de Apps de Zapier.

Acciones disponibles:

Consultar Condiciones de Playa — obtén calidad del agua, clima, condiciones oceánicas y mareas
Consultar Puntuación de Playa — obtener la puntuación y calificación
Buscar Playas — encuentra playas por nombre

Para usar:

Ve a la página de Beach Day API en Zapier y haz clic en Pruébalo
Usa Schedule by Zapier como disparador (para resúmenes diarios o alertas)
Añade una acción de Beach Day API y selecciona una de las acciones anteriores
Conecta tu clave de Beach Day API desde tu Panel
Elige un destino (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

Probar en Zapier → · Página de integración

🔗 Nodo n8n

Usa Beach Day API directamente en tus flujos de n8n — busca playas, consulta condiciones, mareas y más.

npm install n8n-nodes-beachday

Instala desde Configuración → Nodos Comunitarios en n8n, o encuéntralo en npm:

npm → · Página de integración

🤖 Apify Actor

Ejecuta operaciones de Beach Day API como trabajos repetibles en Apify — busca playas, obtén detalle de playa, predicciones de mareas, normativas, servicios y playas mejor puntuadas. Admite ejecuciones programadas, webhooks, exportaciones de datasets (JSON, CSV, Excel) y acceso de agentes IA mediante Apify MCP.

Operaciones disponibles:

Buscar Playas — encuentra playas por nombre, estado o país
Obtener Detalle de Playa — condiciones completas, puntuación, normativas y servicios
Obtener Playas Mejor Puntuadas — playas ordenadas por Beach Day Score actual
Obtener Predicciones de Mareas — datos de mareas de 7 días para cualquier playa
Obtener Normativas de Playa — reglas locales (perros, alcohol, fogatas, etc.)
Obtener Servicios de Playa — servicios en el lugar (salvavidas, estacionamiento, baños)
Obtener Condiciones de Playa — instantáneas históricas de condiciones

Ver en Apify Store → · Página de integración

📘 APIDog (Documentación Interactiva)

Documentación de API interactiva con pruebas de endpoints en vivo, fragmentos de código generados en cURL, JavaScript, Python y más. Explora y prueba cada endpoint desde tu navegador.

Abrir APIDog → · Página de integración

🔄 Apyhub Marketplace

Explora y prueba los endpoints de Beach Day API en Apyhub con un entorno interactivo. Cada endpoint tiene una consola de prueba en vivo — sin código necesario para una primera evaluación.

Endpoints disponibles en Apyhub:

Listar Países — países disponibles con conteo de playas
Buscar Playas — encuentra playas por nombre, estado o país
Obtener Detalle de Playa — condiciones completas, puntuación, normativas y servicios
Obtener Condiciones de Playa — instantáneas históricas basadas en tiempo
Obtener Predicciones de Mareas — datos de mareas de 7 días para cualquier playa
Obtener Normativas de Playa — reglas locales (perros, alcohol, fogatas, etc.)
Obtener Servicios de Playa — servicios en el lugar (salvavidas, estacionamiento, baños)
Obtener Playas Mejor Puntuadas — playas ordenadas por Beach Day Score actual

Ver en Apyhub → · Página de integración

🏠 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 → · Página de integración

🛒 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 → · Página de integración

¿Quieres otro lenguaje? Beach Day API es REST/JSON simple. Puedes usar cualquier cliente HTTP. Las librerías cliente contribuidas por la comunidad para Go, Ruby y PHP son bienvenidas. Ponte en contacto →

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 créditos, account balance and active packages)
list_countries (1 credit)
search_beaches (1 credit)
get_beach (5 créditos)
get_weather (3 créditos)
get_water_quality (3 créditos)
find_swimmable_beaches (10 créditos)

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