Skip to content
SargacastSargacast

Sargacast API for developers

Free, read-only JSON with the daily sargassum level of every Florida beach we track, plus a 7-day outlook for each one. No key and no sign-up.

What the API is

  • Free to use: no key, no account and no sign-up.
  • Read-only JSON over HTTPS: three GET endpoints and nothing to write.
  • CORS is open (Access-Control-Allow-Origin: *), so a web page can call it straight from the browser.
  • Responses are cached at the CDN for about 5 minutes. The data itself is recalculated every hour, when our engine runs.

Quickstart

Copy any of these into a terminal; each one works as it is.

Every beach with today's reading
curl https://sargacast.com/api/v1/beaches
Tomorrow's forecast for one zone
curl "https://sargacast.com/api/v1/beaches?zone=miami-beach&day=tomorrow"
One beach with its 7-day outlook
curl https://sargacast.com/api/v1/beaches/south-pointe
Whether the data is being served, and how fresh it is
curl https://sargacast.com/api/v1/health
Any page of the site as Markdown, for agents and scripts
curl -H "Accept: text/markdown" https://sargacast.com/en/beaches/south-pointe

Responses and errors

Every answer is a JSON envelope. A success carries "ok": true and the data. An error carries "ok": false, an HTTP status and an error object with a code, a message and usually a hint that says what to do next.

An unknown beach, for example:
{
  "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."
  }
}

The error codes:

  • validation_failed (422): a parameter is invalid; the hint names it and lists the values it takes.
  • not_found (404): no beach has that slug, or the path is not part of the API; the hint says how to list the slugs.
  • method_not_allowed (405): the API is read-only, so use GET.
  • unavailable (503) and internal (500): the database did not answer or a query failed. Try again in a few minutes.

What the fields mean

  • index_value: the Sargassum Meter, from 0 (none) to 10 (heavy). It is null when a beach has no recent data.
  • level: the meter in words: clean (0–3), moderate (4–6) or heavy (7–10).
  • status: ok for a recent reading, stale when the last reading is older than it should be (still shown, with its age), no_data when there is nothing recent.
  • confidence: from 0 to 1, how much the value can be trusted. It rises with more inputs and fresher ones.
  • computed_at: when our engine last calculated the reading (every hour). It is not the satellite pass: the satellite input is a 7-day composite, and each beach page shows its date.
  • forecast (one beach only): up to 7 days, each with date, index_value, level, confidence, lead_days (days after the calculation, 0 for the same day) and kind: forecast for lead_days 0 to 3, trend for the later days, which are a rougher outlook.
  • zone_slug is what ?zone= filters on; reports_today counts today's community reports for the beach.

Machine-readable docs

Usage terms

  • Free to use, including in apps and articles, with the visible credit “Data: Sargacast (sargacast.com)” and a link to the site.
  • Please cache responses and avoid more than about one request per minute per client.
  • It is a guide, not an official safety or health warning.
  • For heavy or commercial use, or a higher volume, write to: hola@sargacast.com

Questions

Questions, a bug or a field you would like to see: one person reads every message at hola@sargacast.com