Watershed map of North America with MapLibre GL JS
Every river in North America that drains at least 1,000 square kilometers, about 400 square miles, colored by the sea it ends up in. Click anywhere, or look up a town, to drop some rain there. A white line follows it down to the sea, and every river upstream that drains past the same spot lights up.
The Mississippi and its branches drain about two fifths of the lower 48 states, from the Rockies in Montana to the Appalachians in Pennsylvania. In Glacier National Park, rain can go three ways: west down the Flathead and the Columbia to the Pacific, north down the St. Mary and the Saskatchewan to Hudson Bay, or east down the Marias and the Missouri to the Gulf of Mexico. Fargo and Winnipeg drain north, down the Red River, to Hudson Bay too. Rain on Salt Lake City and Reno never reaches the sea. It ends in the Great Salt Lake and Pyramid Lake, in the Great Basin.
The rivers come from HydroRIVERS, which traces every river in the world from satellite measurements of the ground's height and links each stretch to the next one downstream. Rain on the map runs to the nearest river that drains 1,000 km² or more, so near a ridge between two rivers it can land on the wrong side. The river names come from Natural Earth, which names the bigger rivers, so a small river's stretch goes unnamed, and some names may be off.
Build it yourself
A command downloads HydroRIVERS' rivers for North America and keeps the ones that drain at least 20,000 km², and a page draws them. Click a river to light up everything upstream of it, and its way to the sea in white. It's the map above for the bigger rivers only, without the colors, names, or town search. It was tested with MapLibre GL JS 6.15 and mapshaper 0.6 in Chromium and Node.js 22.
What you need
- Node.js 18 or later, for mapshaper.
- A browser key with the Map tiles product, made as API keys shows. Add
http://localhost:*to its allowed origins, so it works from your computer while you build. Map tiles are free, and signing up takes a minute, with no credit card.
Get the rivers
Make a folder for the map, and in it download HydroRIVERS for North America, 66 MB, and turn the rivers that drain at least 20,000 km² into GeoJSON with mapshaper:
curl -O https://data.hydrosheds.org/file/HydroRIVERS/HydroRIVERS_v10_na_shp.zip
npx mapshaper@0.6 -i HydroRIVERS_v10_na_shp.zip -filter 'UPLAND_SKM >= 20000' -filter-fields HYRIV_ID,NEXT_DOWN,UPLAND_SKM -o rivers.json format=geojson precision=0.001
mapshaper reads the shapefile straight from the zip, and prints Retained 21,600 of 986,463 features. Each stretch of river keeps three of its fields: its own ID in HYRIV_ID, the ID of the stretch it flows into in NEXT_DOWN, which is 0 where it reaches the sea, and the area it drains in UPLAND_SKM, in square kilometers. rivers.json comes to about 5 MB.
Make the page
Next to rivers.json, make index.html, with your browser key in place of mapricot_pk_…:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Where the rain goes</title>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/maplibre-gl@6.15.0/dist/maplibre-gl.css">
<script type="importmap">
{
"imports": {
"maplibre-gl": "https://cdn.jsdelivr.net/npm/maplibre-gl@6.15.0/+esm"
}
}
</script>
</head>
<body style="margin: 0">
<div id="map" style="height: 100vh"></div>
<script type="module">
import * as maplibregl from "maplibre-gl";
const map = new maplibregl.Map({
container: "map",
style: "https://api.mapricot.com/tiles/v1/styles/dark.json?key=mapricot_pk_…",
bounds: [
[-128, 22],
[-64, 56],
],
});
await map.once("load");
const rivers = await (await fetch("rivers.json")).json();
const next = new Map();
const upstream = new Map();
for (const { properties } of rivers.features) {
next.set(properties.HYRIV_ID, properties.NEXT_DOWN);
if (!upstream.has(properties.NEXT_DOWN)) upstream.set(properties.NEXT_DOWN, []);
upstream.get(properties.NEXT_DOWN).push(properties.HYRIV_ID);
}
map.addSource("rivers", { type: "geojson", data: rivers, attribution: "Rivers: WWF HydroSHEDS" });
const width = ["interpolate", ["linear"], ["sqrt", ["get", "UPLAND_SKM"]], 140, 0.5, 1800, 4];
const none = ["in", ["get", "HYRIV_ID"], ["literal", []]];
const layout = { "line-cap": "round" };
map.addLayer({ id: "rivers", type: "line", source: "rivers", layout, paint: { "line-color": "#4dabf7", "line-opacity": 0.4, "line-width": width } });
map.addLayer({ id: "upstream", type: "line", source: "rivers", filter: none, layout, paint: { "line-color": "#4dabf7", "line-width": width } });
map.addLayer({ id: "downstream", type: "line", source: "rivers", filter: none, layout, paint: { "line-color": "#ffffff", "line-width": 3 } });
map.on("click", ({ point }) => {
const near = [
[point.x - 10, point.y - 10],
[point.x + 10, point.y + 10],
];
const [river] = map.queryRenderedFeatures(near, { layers: ["rivers"] });
if (!river) return;
const down = [];
for (let id = river.properties.HYRIV_ID; next.has(id); id = next.get(id)) down.push(id);
const up = [];
const queue = [river.properties.HYRIV_ID];
while (queue.length) {
const id = queue.pop();
up.push(id);
queue.push(...(upstream.get(id) ?? []));
}
map.setFilter("downstream", ["in", ["get", "HYRIV_ID"], ["literal", down]]);
map.setFilter("upstream", ["in", ["get", "HYRIV_ID"], ["literal", up]]);
});
</script>
</body>
</html>
nextmaps each stretch to the stretch it flows into, andupstreamthe other way, to every stretch that flows into it.- Each river is as wide as the square root of the area it drains, so the Mississippi is wide and its smallest branches thin, and all are faint until clicked. The
upstreamanddownstreamlayers draw the same rivers again, filtered to only the stretches in their lists, which start empty. - Clicking looks for a river within 10 pixels. The way to the sea follows
nextfrom stretch to stretch until it runs out. Everything upstream comes from followingupstreamback, through every branch, with a queue of stretches still to look at.
Open it
Serve the folder with npx serve or python3 -m http.server, and open the address it prints. Opened straight from the file, the map stays blank, as Open the page explains. You should see North America's big rivers, faint blue on a dark map. Click the Mississippi near New Orleans to light up its branches from Montana to Pennsylvania.
Change 20000 to 5000 in the mapshaper command for twice as many rivers, though the page will take longer to load.
Data
- Rivers: HydroRIVERS v1.0, from Lehner, B., Grill G. (2013): Global river hydrography and network routing: baseline data and new approaches to study the world's large river systems. Hydrological Processes, 27(15): 2171–2186, under the HydroSHEDS license in its technical documentation
- River names, seas, and lakes: Natural Earth (public domain)
- Town search: Mapricot's geocoding API
- Map: OpenStreetMap contributors (ODbL), in Mapricot's map tiles
This map incorporates data from the HydroSHEDS version 1 database which is © World Wildlife Fund, Inc. (2006-2022) and has been used herein under license. WWF has not evaluated the data as altered and incorporated within this map, and therefore gives no warranty regarding its accuracy, completeness, currency or suitability for any particular purpose. Portions of the HydroSHEDS v1 database incorporate data which are the intellectual property rights of © USGS (2006-2008), NASA (2000-2005), ESRI (1992-1998), CIAT (2004-2006), UNEP-WCMC (1993), WWF (2004), Commonwealth of Australia (2007), and Her Royal Majesty and the British Crown and are used under license. The HydroSHEDS v1 database and more information are available at hydrosheds.org.