ACE Tracker
Atlantic & Eastern Pacific Hurricane ACE Tracker
Tracks Accumulated Cyclone Energy (ACE) for Atlantic and Eastern Pacific hurricane seasons with storm-by-storm data from 1991 onward. Publishes a web dashboard rebuilt hourly during hurricane season from NOAA/NHC data. It's a hobby data site, not a forecast: for watches, warnings, and forecasts, go to the National Hurricane Center.
Live Site
Rebuilt hourly May–November and every 3 hours December–April. Hurricane seasons: Eastern Pacific May 15 – Nov 30, Atlantic Jun 1 – Nov 30. Each basin shows when its storm data is from ("Best-track data as of …"), which can lag the page build by a few hours; the build time is in the footer.
Features
- Live season tracking — current season ACE rebuilt hourly from NHC's real-time best track, with a data-as-of stamp (and relative "x hours ago") next to each basin's numbers
- Honest labels — in-season ACE is marked preliminary (it's revised in NOAA's spring HURDAT2 release), and landfalls estimated from a live track are marked est.
- Dual basin — Atlantic and Eastern Pacific, toggle between them on each page
- Dark/light mode — defaults to system preference for first-time visitors, persisted across sessions after that
- Season progress bar — shows current day and percent complete
- Landfall data — each storm shows where it made landfall and its intensity at the moment of impact (not just peak). Multi-landfall storms show all locations (e.g.
Florida (Cat 1) · Louisiana (Cat 3)). Storms that never made landfall are labeled Fish Storm. For the current season, landfalls come from the preliminary track and are marked est. until NHC's post-season report
- NHC development alert — amber banner appears when NHC is tracking an area with Medium (≥40%) or High (≥70%) formation chances, with direct link to the NHC Tropical Weather Outlook
- Honest season comparisons — Season Insights show both same-date historical averages (what's typical by this point in the season) and full-season averages, so early-season numbers aren't misleadingly compared against totals that take six months to accumulate
- Storm track maps — interactive Leaflet maps per storm with intensity color-coding; expandable inline on the dashboard, with a loading indicator while tiles load
- Spaghetti model tracks — active storms overlay multi-model forecast tracks on the storm map, toggleable per storm. Each model is labeled with its run time (e.g.
GFS 18Z Sep 26), and a model whose latest run is more than 24 hours behind the newest run for that storm is left off
- Wind speed unit toggle — switch the dashboard between knots, mph, and km/h; persisted across visits, defaults to knots
- Shareable storm links — copy a direct link to any storm on the dashboard via the 🔗 button on each row; opening the link auto-switches basin and expands that storm
- NHC forecast cone — active storms show their official 5-day forecast cone graphic with its advisory time, fetched from NHC once per run and served from our own domain (not hotlinked)
- Active storms map and distance from you — one map of every active storm in both basins. Search a place, use your location or tap the map to see each storm's distance and direction, and whether you're in the forecast cone or wind field. A remembered location (kept only in your browser) adds a "Nearest storm" badge to the top of the dashboard
What is ACE?
Accumulated Cyclone Energy (ACE) measures total hurricane season activity by combining storm intensity and duration. It's calculated by squaring the maximum sustained wind speed (in knots) at each 6-hour synoptic time when the system is at tropical storm strength or higher, then summing across all storms.
Formula: ACE = Σ(V²max) × 10⁻⁴
A long-lived major hurricane contributes far more ACE than a brief tropical storm. NOAA uses seasonal ACE totals to classify activity levels.
NOAA Season Classifications (both basins)
| Classification | ACE |
|---|
| Extremely Active | ≥ 159 |
| Above Normal | 126 – 159 |
| Near Normal | 73 – 126 |
| Below Normal | < 73 |
Quick Start
Requirements
- Python 3.11 or 3.12 (3.13+ isn't supported yet — see Troubleshooting)
- Internet connection (for fetching live data)
Installation
git clone https://github.com/jeremypfi/ace-tracker.git
cd ace-tracker
pip3 install -r requirements.txt
Run
python3 ace_tracker.py
Generates in data/:
ACE_Dashboard.html — current season dashboard (open in any browser)history.html — all-seasons history pagerecords.html — storm records since 1991what-is-ace.html — ACE explainer and calculatorapi.html — JSON API and RSS docs (every field, examples)
Run tests
python3 test_ace_tracker.py # unit + smoke tests
python3 test_ui.py # browser tests (needs requirements-dev.txt + `playwright install chromium`)
python3 verify_pr.py # unit tests + syntax check + a full live tracker run + browser tests
All tests must pass before committing. Use the /pre-commit skill in Claude Code for the full checklist.
Public data
Full field-by-field docs with examples: aceofcanes.com/api.html.
- JSON API:
https://aceofcanes.com/api/v1/season.json has both basins' current season: ACE totals, classification, counts, rank, every storm with its landfalls and track points, and yearly ACE since 1991. Wind is in knots, current-season values are preliminary, and the version field is 1. Fields may be added to v1, but a rename or removal will ship as /api/v2/.
- RSS:
https://aceofcanes.com/feed.xml adds an item for each named storm as it forms.
- Storm pages: every current-season storm has its own page at
https://aceofcanes.com/storm/<name>-<year>.html (for example storm/polo-2026.html), with the track map, forecast cone and model tracks while active, ACE, landfalls and its own share card. Each storm's url is in the JSON.
Project Structure
ace-tracker/
├── ace_data.py # Data fetch, ACE calc, plain-text report generation
├── ace_html.py # Dashboard, history, records, and What Is ACE? page rendering
├── ace_feeds.py # JSON API (api/v1/season.json) and RSS feed (feed.xml) builders
├── ace_assets.py # CSS and JS blocks shared by the dashboard and storm pages
├── ace_storm_pages.py # One page per current-season storm (storm/<name>-<year>.html)
├── ace_cards.py # Live season share card (og/season-<hash>.png, drawn with Pillow)
├── ace_tracker.py # CLI entrypoint — wires the modules above together
├── test_ace_tracker.py # unit + smoke tests
├── test_ui.py # Playwright browser tests against the fixture site
├── ui_fixture_site.py # Builds the whole site offline from fixtures/ for test_ui.py
├── fixtures/ # Saved NHC feeds + HURDAT2 snippet for offline fetcher tests
├── verify_pr.py # Consolidated PR check: tests + syntax check + a live tracker run + UI tests
├── smoke_test.py # Pre-deploy structural checks on the built data/ folder
├── freshness_check.py # Live-site staleness check behind the site-alert issue
├── requirements.txt # Python dependencies
├── ace.png # Site logo (favicon + OG image)
├── ace_preview.png # 1200x630 social share card (copied into data/ at publish time)
├── landfall_cache.json # Cached landfall geocoding results (gitignored, built by CI)
├── CNAME # Custom domain for GitHub Pages (aceofcanes.com)
├── robots.txt # Search engine crawl rules
├── sitemap.xml # Sitemap for search engine indexing
├── CLAUDE.md # Project instructions for Claude Code
├── CONTRIBUTING.md # Contribution guidelines
├── images/ # Reference/marketing images
├── .claude/skills/ # /pre-commit, /season-start, /verify-data
├── .github/
│ ├── workflows/
│ │ ├── tests.yml # CI: runs tests on push/PR (Python 3.11, 3.12)
│ │ ├── publish.yml # Scheduled: generates, smoke-tests and deploys the dashboard hourly in season
│ │ └── freshness.yml # Hourly: starts a missed publish; opens/closes a site-alert issue if the site goes stale
│ ├── dependabot.yml # Automated dependency updates
│ └── CODEOWNERS # @jeremypfi must approve all PRs
├── SECURITY.md
└── data/ # Published as the site (html generated + gitignored; ace.png and vendor/ committed)
├── ace.png
├── ACE_Dashboard.html # copied to index.html at publish time
├── history.html
├── records.html
├── what-is-ace.html
├── api.html
├── vendor/ # Self-hosted Leaflet 1.9.4 and Chart.js 4.5.1, with licenses
└── cones/ # NHC forecast cone images, fetched fresh each run (gitignored)
Data Sources
- NOAA HURDAT2 — official historical best-track database (1991–present) via the Tropycal library
- NHC Real-time Best Track — current season preliminary data (
include_btk=True in Tropycal), updated continuously during active storms
- NHC Tropical Weather Outlook — XML feeds (
TWOAT.xml / TWOEP.xml) parsed every run for active disturbances with development potential
- NHC CurrentStorms.json — active storm metadata used to locate and cache each storm's 5-day forecast cone graphic
- NOAA CPC — season classification thresholds and 1991–2020 climatological normals
- Natural Earth — 10m shapefiles (via Cartopy) for offline landfall geocoding
How Landfall Detection Works
Historical storms (completed seasons) use the official HURDAT2 'L' landfall markers, which record the exact time and position of each landfall. These markers aren't added to the real-time best-track data until the post-season analysis, so active-season storms use a geographic fallback: track points are checked against Natural Earth shapefiles using exact point-in-polygon containment. Those landfalls are shown as est., and only landfalls at tropical-storm strength or stronger count toward the landfall ACE share. Results are cached in landfall_cache.json and persisted via GitHub Actions cache so geocoding only runs for new or updated storms. The Natural Earth shapefiles themselves (~20 MB) are also cached by the publish workflow (key naturalearth-10m-cultural-v1; bump the suffix to force a fresh download).
Configuration
Key constants, mostly in ace_data.py (OUTPUT_FOLDER is the one exception — it stays in ace_tracker.py since only main() uses it):
| Constant | Purpose |
|---|
START_YEAR | Earliest year included in historical data (default: 1991) |
OUTPUT_FOLDER | Where HTML files are saved (default: data/) — defined in ace_tracker.py |
LANDFALL_CACHE_PATH | Path to the landfall geocoding cache (default: repo root) |
BASINS | Normal ACE values and average storm counts per basin |
BACKUP_DATA | Fallback season data used if NOAA is unreachable |
SPAGHETTI_MODELS | Forecast models drawn on active-storm maps |
SPAGHETTI_MAX_RUN_LAG_HOURS | A model whose latest run trails the storm's newest model run by more than this is left off the map (default: 24) |
Troubleshooting
Script can't fetch data
The tracker falls back to BACKUP_DATA automatically. You'll see:
✗ Error loading Tropycal data → Using backup data (yearly totals only)
Landfall cache miss on first CI run
The landfall_cache.json is built on the first run and cached by GitHub Actions. The first run after a fresh clone will geocode all historical storms (~1 min extra). Every subsequent run reads from cache.
"Dropped N malformed row(s) … from HURDAT2 file" warning
NOAA's HURDAT2 file sometimes ships rows with unparseable lat/lon fields, which would crash Tropycal's parser for the whole basin. The tracker drops those rows and names the storms they belong to, and says whether any is from 1991 onward. As of Sept 2026 they are AL211969 and AL231975: "all before 1991, so no effect on this site's data."
setuptools pin
requirements.txt pins setuptools>=84.1.0,<85. The floor is a security fix (GHSA-xmj3-9gf7-h52w). The cap and the Python 3.13+ exclusion in CI date from when Tropycal imported pkg_resources. Tropycal 1.5.2 no longer does, so both are due for a retest.
Credits
- Built with Claude Code (Anthropic)
- Data from NOAA National Hurricane Center via Tropycal
- Maps powered by Leaflet (BSD-2) and the pace chart by Chart.js (MIT), both self-hosted from
data/vendor/ with their licenses. To upgrade one, add a new versioned folder there, update the path and integrity hash in ace_html.py, and test_ace_tracker.py checks the file matches the hash.
- Inspired by hurricane tracking communities
Questions or issues? Open an issue on GitHub or reach out to @jeremypfi
