Methodology and limits

The atlas republishes NOAA's own current risk classes at vacation-zone scale. It does not invent an inundation model. A separate AFAI climatology was attempted and rejected by a predefined back-test, so seasonal sections are editorial.

Current source: NOAA SIR v1.5

satellite-derived The nightly job discovers the current Risk KMZ from NOAA's Daily Sargassum Inundation Risk page. SIR compares nearby AFAI with a multiday baseline over coastal neighborhoods. It is a relative coastal inundation-risk classification, not a measurement of seaweed on sand.

Version 1.5 publishes Low (blue), Warning (yellow), Medium (orange), and High (red). Areas with not enough data are black in NOAA's presentation. The pipeline maps KML integer codes 0 through 3 to those names after checking the product version, declared KML schema, style semantics, and observation date.

Vacation-zone geometry

Every destination has a versioned WGS84 shoreline polyline and a separate offshore box. Only the shoreline polyline can affect current SIR. The box is reserved for climatology work and never substitutes for a shoreline-risk product.

Length-weighted shoreline aggregation

The pipeline samples each polyline at 1-kilometer spacing. Each sample is matched to the nearest SIR shoreline point within 5 kilometers. Equal-distance sampling makes the resulting class shares length-weighted rather than vertex-count weighted.

A headline uses the highest NOAA class that covers at least 20% of matched samples and includes a contiguous run covering at least 10% of all samples. This prevents one isolated point from flipping the page. Coverage below 60% produces “insufficient data” and no headline. The exact parameters are stored in `data/current.json` and tested.

Freshness and timestamps

observed_at is the upstream SIR observation date.
retrieved_at is when the successful pipeline fetched and validated that observation.
built_at is when Astro rendered the static page.

The maps on the homepage and destination pages color the Natural Earth public-domain coastline with NOAA's SIR classes: each stretch of coast takes the class of the nearest point in NOAA's product within 5 kilometers, the same nearest-match rule the destination aggregation uses, and coast with no SIR data nearby stays uncolored. NOAA's own product uses a generalized shoreline, so this redraws where the colors sit (on the real coast) but never what they say; no class is ever recomputed, and the maps go into a withheld state under the same freshness rules as everything else.

The small historical month maps on destination pages are a different dataset: the NOAA AOML OceanWatch 7-day AFAI archive (free use and redistribution per its published terms), composited as a per-cell monthly maximum at roughly 0.09-degree display resolution with one fixed color scale across all months and years, so they are visually comparable. They show raw floating-algae detections, not the risk product and not ratings. AFAI can also flag other floating material, and clouds or sun glint can hide real algae, so an empty-looking month is not proof of a clear month. Cells within roughly 20 km of land are excluded entirely: comparing a quiet January against a peak August showed identical false detection rings hugging every coastline, a known land-adjacency artifact, so the nearshore strip is blanked rather than shown wrong. NOAA's risk archive itself only begins in 2026, which is why these historical views use the underlying satellite record instead.

Freshness has two tiers. An observation within 48 hours renders normally. An observation older than 48 hours still renders, with a visible age note, only when a fetch within the last 36 hours confirmed it is still NOAA's most recent published product (SIR dates carry day resolution and NOAA skips publish days, so being fully in sync with the source can exceed 48 hours). Past 120 hours, or whenever we cannot confirm sync with the source, classes are withheld and the pages say so. A failed fetch updates only pipeline status and preserves the last-good observation file with its original dates.

Structural and review failures

Downloads have connection and read timeouts, compressed-size limits, decompression caps, and an entry-path allowlist. XML declarations for DTDs or entities are rejected, and parsing uses `defusedxml`. Schema drift, empty output, old or regressed observations, and coverage collapse fail ingestion. Plausible unusual distributions publish but add a review alert.

Climatology source and failed gate

The probe used NOAA/AOML's ERDDAP distribution of the 7-day cumulative USF AFAI archive, which begins 2016-06-18 and has an uneven time axis. The dataset exposes AFAI and `NaN`, but no independent cloud, glint, land, or contamination flag. Its metadata says AFAI can flag non-Sargassum surface features and can saturate under sun glint, cloud, or thick aerosol. Near-coast pixels are especially difficult to interpret.

Before viewing candidate results, Phase 0 required spring-summer seasonality at Riviera Maya and eastern Barbados, heavy-year behavior for 2018 and 2023, flat-low Aruba and Curacao negative controls, at least 50% monthly finite coverage, and success on untouched 2024. Positive area fraction, the 90th percentile, and integrated positive signal were tested on fixed offshore boxes.

No candidate passed every rule. Integrated positive signal passed the training, heavy-year, control, and coverage checks, but failed the 2024 Riviera Maya holdout. The destination satellite climatology therefore does not ship.

Editorial seasonal fallback

editorial Destination month sections summarize only NOAA's broad regional description: the belt develops in winter, moves north through spring, is often more active into summer, and usually eases in fall. These are not destination ratings and are visually separated from SIR. Sources: NOAA CoastWatch FAQ and NOAA/AOML overview.

Webcam checks

Every committed camera URL returned a successful response on its recorded verification date. YouTube is embedded only after a separate privacy-enhanced embed URL succeeds, and the player is click-to-load. Other cameras are outbound cards. The nightly job can change a dead URL to “cam offline.” A working camera is still only one local view.

Licensing and attribution

AFAI's published ERDDAP terms allow free use and redistribution with warranty and legal-use limits. The SIR page publishes the experimental disclaimer but no separate dataset license was found. A clarification email is drafted but was not sent during this build. The site remains non-commercial, with no advertising or affiliate links, while clarification is pending. The full repository records are `DATA_SOURCES.md` and `PHASE0_FINDINGS.md`.

Deliberate limits

No resort scores, date-specific trip comparisons, confidence percentages, basin-wide index, homemade risk model, Florida or Gulf pages, automated alerts, crowdsourced photos, USF bulletin republication, or destination-by-month pages are included in v1.