Splitshot Weather — map starters

Animated US weather radar on a map, in one HTML file and about 80 lines of JavaScript. No build step, no framework, no bundler.

Real tiles from the API, composited at full colour depth. The basemap under them is Esri's dark canvas, which is what leaflet/ draws; web/ uses CARTO's vector style, so its ground looks slightly different. The radar is identical.

	map library	folder
MapLibre GL	vector basemap, WebGL	web/
Leaflet	raster tiles, no WebGL needed	leaflet/

Both do the same thing and are the same length. Pick whichever matches the map you already have — the API does not care, and neither file is a wrapper around the other.

Built on the Splitshot Weather API — NOAA radar, rainfall, lightning, wind and temperature rendered as map tiles, plus point forecasts and history. This repo is the shortest path from an API key to something moving on a screen.

Run it

1. Get a key. splitshotweather.com — the trial is free and takes no card. Current limits are on the pricing page.

2. Paste it into config.js, replacing PASTE_YOUR_KEY_HERE.

3. Serve the folder and open whichever example you want:

   python3 -m http.server 8000
   # http://localhost:8000/web/       MapLibre GL
   # http://localhost:8000/leaflet/   Leaflet
   

Both read the same config.js at the root, so the key goes in one place.

Opening the files directly as a file:// URL will not work: both use an ES module to import config.js, and browsers refuse module imports over file://. Any static server will do — the one-liner above, npx serve, whatever you already run.

How the API works

Two calls. Read the manifest, then load tiles.

The manifest tells you which frames exist right now:

curl -H "x-api-key: YOUR_KEY" \
  https://api.splitshotweather.com/manifest/composite.json

{
  "product": "composite",
  "cadenceMinutes": 5,
  "maxZoom": 8,
  "units": "dBZ",
  "frames": ["20261026-1945", "20261026-1950", ...],  // observed, oldest first
  "latest": "20261026-2140",
  "forecast": [{ "ts": "20261026-2145", "leadMinutes": 5 }, ...],
  "tileUrlTemplate": "/tiles/composite/{ts}/{z}/{x}/{y}.png",
  "forecastTileUrlTemplate": "/tiles/composite-fcst/{ts}/{z}/{x}/{y}.png",
  "legend": [{ "value": 5.0, "unit": "dBZ", "rgb": [126, 211, 126] }, ...]
}

Always read the manifest rather than deriving timestamps from the clock. Frames are published when the upstream data lands, which is not on a tidy schedule, and a guessed timestamp is a 404.

Then substitute a timestamp into the template and hand the result to your map library as a raster source. That is all either example does.

The legend array is the exact colour ramp the tiles were rendered with, so a legend in your UI can be generated from it instead of hard-coded and drifting.

Two ways to pass the key

x-api-key: YOUR_KEY header	Use this wherever you control the request — the manifest fetch, /forecast, /history.
?key=YOUR_KEY query string	For raster tiles, where the map engine issues the request and gives you no way to attach a header.

The key is stripped at the edge before anything is cached or logged, and the tile cache key ignores it, so every customer shares one cached tile.

Other endpoints

GET /manifest/{product}.json
GET /tiles/{product}/{ts}/{z}/{x}/{y}.png
GET /forecast/{lat},{lon}
GET /history/{lat},{lon}/{iso8601}
GET /points/lightning/{ts}.json      lightning as GeoJSON points
GET /alerts                          active NWS alerts, as GeoJSON
GET /alerts/{lat},{lon}              just the ones over one point

Products: composite (radar reflectivity), qpe-1h and qpe-24h (rainfall accumulation), lightning, wind, temperature. Each has its own manifest, legend and cadence — change PRODUCT in config.js to try one.

Full reference: splitshotweather.com/docs.html

Two things worth copying

Mount every frame, switch opacity. The obvious approach — one source whose URL you rewrite on each step — makes the map tear down and refetch the entire tile set every time, so scrubbing flickers and burns requests re-downloading frames you just had. Mounting each frame as its own layer and flipping its opacity — raster-opacity in MapLibre, setOpacity() in Leaflet — only touches tiles that are already in memory.

The cost is that all frames load up front. At 24 observed frames that is real, so a production app usually mounts a window around the current frame rather than the whole timeline.

A dark basemap. The radar ramp starts at light green. On a light basemap the weak returns — which are most of the pixels — wash out completely.

In Leaflet, maxNativeZoom, not maxZoom. Radar is rendered to zoom 8. Setting maxZoom: 8 on the layer makes Leaflet hide the radar the moment someone zooms past it — exactly when they are looking closest at a storm. maxNativeZoom: 8 keeps requesting the deepest tiles that exist and upscales them instead. (Verified: at map zoom 9 the basemap serves z9 while the radar serves z8, stretched, still drawn.)

Before you ship this

config.js puts the key in front-end JavaScript, which is fine for a demo you run locally and wrong for anything you deploy. Anyone who opens devtools can read it, and usage bills to you.

In production, keep the key on your server and proxy the tile requests. Your server attaches the key; the browser never sees it.

License

MIT — see LICENSE. Use it as a starting point, not as a dependency.

Issues and pull requests are welcome here. This directory is published from the API's own repository, so a fix lands next to the service it demonstrates.

Weather data is derived from NOAA / National Weather Service sources, which are in the public domain. The rendering is Splitshot Weather's. Note that the API is not for safety-of-life use — see the terms.