API de Sargacast para desarrolladores

JSON gratuito y de solo lectura con el nivel diario de sargazo de cada playa de Florida que seguimos, más una previsión de 7 días para cada una. Sin clave y sin registro.

Qué es la API

Gratis: sin clave, sin cuenta y sin registro.
JSON de solo lectura por HTTPS: tres rutas GET y nada que escribir.
CORS abierto (Access-Control-Allow-Origin: *): una página web puede llamarla directamente desde el navegador.
La CDN guarda las respuestas unos 5 minutos. Los datos se recalculan cada hora, cuando corre nuestro motor.

Primeros pasos

Copia cualquiera de estos comandos en una terminal; todos funcionan tal cual.

Todas las playas con la lectura de hoy

curl https://sargacast.com/api/v1/beaches

El pronóstico de mañana para una zona

curl "https://sargacast.com/api/v1/beaches?zone=miami-beach&day=tomorrow"

Una playa con su previsión de 7 días

curl https://sargacast.com/api/v1/beaches/south-pointe

Si los datos se están sirviendo y qué tan recientes son

curl https://sargacast.com/api/v1/health

Cualquier página del sitio en Markdown, para agentes y scripts

curl -H "Accept: text/markdown" https://sargacast.com/en/beaches/south-pointe

Respuestas y errores

Cada respuesta es un sobre JSON. Un acierto lleva "ok": true y los datos. Un error lleva "ok": false, un código HTTP y un objeto error con un código, un mensaje y casi siempre una pista (hint) que dice qué hacer.

Por ejemplo, una playa que no existe:

{
  "ok": false,
  "error": {
    "code": "not_found",
    "message": "No beach with slug no-such-beach",
    "hint": "List the beach slugs with GET https://sargacast.com/api/v1/beaches (the slug field of each entry). The public API is described at https://sargacast.com/openapi.json and https://sargacast.com/en/developers."
  }
}

Los códigos de error:

validation_failed (422): un parámetro no es válido; la pista lo nombra y da los valores que acepta.
not_found (404): ninguna playa tiene ese slug o la ruta no es parte de la API; la pista dice cómo listar los slugs.
method_not_allowed (405): la API es de solo lectura; usa GET.
unavailable (503) e internal (500): la base de datos no respondió o una consulta falló. Vuelve a intentarlo en unos minutos.

Qué significa cada campo

index_value: el Sargazómetro, de 0 (nada) a 10 (mucho). Es null cuando una playa no tiene datos recientes.
level: el medidor en palabras: clean (0–3), moderate (4–6) o heavy (7–10).
status: ok para una lectura reciente, stale cuando la última lectura es más vieja de lo debido (se muestra igual, con su antigüedad), no_data cuando no hay nada reciente.
confidence: de 0 a 1, cuánto se puede confiar en el valor. Sube con más fuentes y más recientes.
computed_at: cuándo nuestro motor calculó la lectura por última vez (cada hora). No es el pase del satélite: el dato satelital es un compuesto de 7 días y cada ficha de playa muestra su fecha.
forecast (solo una playa): hasta 7 días, cada uno con date, index_value, level, confidence, lead_days (días desde el cálculo, 0 para el mismo día) y kind: forecast para lead_days 0 a 3, trend para los días siguientes, que son una tendencia más aproximada.
zone_slug es lo que filtra ?zone=; reports_today cuenta los reportes de la comunidad de hoy en esa playa.

Documentación para máquinas

Condiciones de uso

Uso gratuito, también en apps y artículos, con el crédito visible “Data: Sargacast (sargacast.com)” y un enlace al sitio.
Guarda en caché las respuestas y no pases de una consulta por minuto por cliente, más o menos.
Es una guía, no un aviso oficial de seguridad ni de salud.
Para un uso intensivo o comercial, o más volumen, escribe a: hola@sargacast.com

Preguntas

Preguntas, un error o un campo que te gustaría ver: una sola persona lee cada mensaje en hola@sargacast.com