Global Watersheds Web App – Help & About
This is the combined Help and About page for the Global Watersheds web app at https://mghydro.com/watersheds/. The web app can find the watershed (drainage area) upstream of almost any place on Earth. It uses the latest, state-of-the-art global datasets, and is faster than most other methods.
Getting Started: A watershed, or drainage basin, is the area upstream or upslope of a point on the earth's surface.
To get started, click somewhere on the map, then click the button Delineate.
The app will show you the watershed boundary as a red line, and the upstream river network as a set of blue lines.
Have fun exploring! I hope this app helps you raise your "watershed consciousness." Water connects us all, and our waterways are precious resources to be protected and conserved.
Keep reading for more detailed information about Global Watersheds web app.
Created with the datasetsMERIT-Hydro, MERIT-Basins, and HydroSHEDS.
Delineation with USGS data and methods (for the continental United States only) is done via their API, called the Hydro Network-Linked Data Index (NLDI). Curious programmers can do much more with these data using the API directly or via the Python library pynhd.
If you use the app in any published work, you can cite the web page, or if you prefer, the GitHub repository which has a DOI from Zenodo: 10.5281/zenodo.7314287
Heberger, Matthew. delineator.py: fast, accurate global watershed delineation using hybrid vector- and raster-based methods. 2022. https://doi.org./10.5281/zenodo.7314287
The app is free and has no advertising. The web hosting costs around $25 per month.
If you found this web app fun or useful, or if it saved you time in your work, consider helping to offset my web hosting cost. via Buy Me a Coffee. ☕ Many cups of coffee were consumed while coding the app!
If you have feedback or suggestions, please get in touch at matt@mghydro.com. I always love hearing what people are doing with the app.
There is no guarantee of the correctness or suitability of these results for any purpose. The author assumes no liability for any harm or damages that result from the use of these data. You should carefully review the results and verify their accuracy.
If you want to download geodata of your watershed or flowpath, open "Options," and check the box "Make downloadable." Any new watersheds or flowpaths that you create while this box is checked will be saved on the server and available for download.
Four download formats are available:
I have released open-source code for doing watershed delineation on your own computer with Python. This code is based on the same hybrid method used in the web app. One advantage of the Python script is that you can run it in "batch mode" to delineate hundreds or thousands of watersheds. The Python script also has several parameters that you can change that alter its performance. By contrast, in the web app, most of these parameters are hard-coded for the sake of simplicity and speed. On the other hand, the Python scripts are slower than the web app, especially for large watersheds. Visit: https://github.com/mheberger/delineator
For most users, it will be faster to use the API. That way, you will be able to take advantage of the features that make the web app faster.
I've set up an API so you can get watershed boundaries, upstream river networks, and downstream flowpaths without using the web map interface. You can use the API with any programming language to automate your workflows, for example to create hundreds (or thousands!) of watersheds. I wrote a blog post about how to do this with Python, and you can download the demo code in a Jupyter notebook. If you have code in another language, please send it to me and I'll post that too.
To use the API, you need to provide a carefully formatted URL. There are two different links -- one for watershed boundaries and another for upstream river networks. At present, I've only set up the API to work with MERIT-Hydro data.
https://mghydro.com/app/watershed_api
https://mghydro.com/app/upstream_rivers_api
https://mghydro.com/app/flowpath_api
You need to append at least two parameters (lat, lng) and an optional third parameter for the precision. Parameters are to be entered as a query string:
lat: a number from -180 to +180.
lng: a number from -60 to +85.
precision: "low" or "high", without quotes.
Optional: if omitted, defaults to "low."
simplify: "true" or "false", without quotes.
Optional: defaults to "false."
beautify: "true" or "false", without quotes.
Optional: defaults to "false."
See the section Simplify or Beautify for a description of what those parameters do.
Note that if your watershed has an area of over 50,000 km², the app will automatically revert to lower-precision mode.
Latitude and longitude should be in decimal degrees (31.416)
https://mghydro.com/app/watershed_api?lat=43.253&lng=-77.609&precision=high
https://mghydro.com/app/upstream_rivers_api?lat=43.253&lng=-77.609&precision=high
https://mghydro.com/app/flowpath_api?lat=-3.913&lng=29.84&precision=high
If the server could handle your request and create a watershed, you will get the HTML status code 200, and the
body of the response will be of mimetype="application/json".
If there is a problem with one of your inputs, you will get a 400 Bad Request status code. For any other kind of error where the app cannot create a watershed (for example, your outlet point is over the ocean), you will get a 404 Not Found status code.
If you see a status code of 500, Internal Server Error, that means something is wrong, so please send me
an email and I'll see if I can fix it.
The response is plain text GeoJSON. Inside is a FeatureCollection. Watersheds only have a single Feature, a Polygon that represents the watershed boundary. (Sometimes the app produces multi-part polygons, but the extra parts are usually the size of single pixels. I programmed the app to discard these, as it makes managing the data much simpler.)
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"type": "Polygon",
"coordinates": [
[
[80.51958, 40.11708], [-80.51375, 40.11791], ... ,
[-80.51958, 40.11708]
]
]
},
"properties": {
"area_km2": "421",
"outlet_lat": 40.23,
"outlet_lng": -80.61
}
}
]
}
The rivers GeoJSON looks similar. But here, the FeatureCollection will usually contain multiple Features, as each river reach, or segment, is a separate Feature.
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"type": "LineString",
"coordinates": [
[-77.64167, 43.12167], [-77.66083, 43.11083],
[-77.67417, 43.1075], [-77.67833, 43.09583]
]
},
"properties": {
"comid": 72056019,
"sorder": 4
}
},
...
{
"type": "Feature",
"geometry": {
"type": "LineString",
"coordinates": [
[-77.92583, 42.06417], [-77.93083, 42.07083],
[-77.93667, 42.0725], [-77.9475, 42.06917]
]
},
"properties": {
"comid": 72058947,
"sorder": 1
}
}
]
}
With the API, you can plug the URL right into QGIS:
Protocol: HTTP(S), Cloud, etc. You can leave Encoding as Automatic. (The API returns UTF-8.)GeoJSON.
Adjust the symbology, and you can have something that looks like this:
During my PhD research in hydrology and remote sensing, I had to delineate thousands of watersheds. I needed a routine that was fast and accurate, and I wasn't happy with any of the existing software that I tried. I ended up writing some code in Python to do the job. I "invented" a technique that uses both vector- and raster-based data. Using this combination of two data types makes this method fast and accurate. Most important, it works on a regular laptop. I write invented in quotes because I could not find this "hybrid" method described in the literature. Nevertheless, I was surprised no one had written about this method. Several months later, I found a conference paper from 1999 describing the method, although the authors did not use the word "hybrid." So, let's say I "rediscovered" it.
I thought my Python scripts were useful, so I shared them on GitHub. This is great for other programmers and scientists. But what about the other 99% of people? I decided to convert the scripts into an interactive website where anyone can find a custom watershed.
As far as know, this is the only (free) app that can delineate watersheds anywhere in the world. It is also much faster than any other method I've tried.
I hope you enjoy using the Global Watersheds app. I am endlessly fascinated by exploring waterways around the world. I hope the app helps you see the world in a new way!
I spent a lot of time searching for an app that delineates watersheds. I was surprised that something like this did not already exist. Nevertheless, I found some other great sites that are somewhat related:
In my testing, I found many areas where the watershed delineation results are not very good. It is important to remember that automated watershed delineation by computer is not always correct. If you are using the results for science or engineering, it is imperative that you check your results.
There are a number of causes of errors. They are especially common where the terrain is flat, such as plains and river deltas. While real-world rivers branch or braid, you will notice that the app's flow paths are always confined to a single channel. This is because the input datasets were created using a deterministic algorithm called D8 that always routes flow in one of 8 directions on a grid. As a result, the app is unable to simulate distributaries, where the flow in a river splits or fans out.
Typical problem areas include:
Unfortunately, neither MERIT-Hydro nor HydroSHEDS have data for some islands. Hawaii is missing, as are the Azores. However, there is data for the Canary Islands, Fiji, Tuvalu, the Galapagos, and many others. I recently found a dataset called HDMA that includes data for many of these smaller islands, and I may consider adding it. Or maybe small islands will be included in HydroSHEDS version 2?
The app offers two main functions: "Downstream - trace flow" or "Upstream - delineate watershed."
Tracing the flow downstream gives you an (approximate) flow path to the ocean or to an inland sink -- what hydrologists call an endorheic basin. The flow path is based on following the steepest slope on a digital map of the earth's elevation. The flow path algorithm used here cannot deal with distributaries, such as those that occur in deltas or braided channels. So, the flowpath may not always follow the route you expect.
A watershed, or drainage basin, is the area upstream or upslope of a point on the earth's surface. Precipitation that falls in a watershed will flow downhill towards the watershed's outlet. If you know the watershed for lake or a river, it can help you understand where the water in that lake or river came from. Watersheds are extremely important in hydrology and environmental science, for everything from studies of flooding, water pollution, aquatic habitat, and much more.
This app considers surface flow paths only. In other words, it does not consider water flowing underground in aquifers. It also ignores most man-made water transfers (in canals or pipelines).
I set up the app using data from three different sources. Here is a short description of each of the 3 options:
Under Options, you can choose the precision of the analysis and the results. Higher-precision mode is the default, and the app will use it whenever you are zoomed in far enough (zoom level 9 or higher on the map) and have chosen MERIT-Hydro as the data source.
For watersheds with an area over 50,000 km², the app will automatically revert to lower-precision mode.
Higher-precision mode is only available with MERIT-Hydro data. I did not implement it for HydroSHEDS. While HydroSHEDS is an excellent dataset, I don't think it is accurate enough to justify doing more detailed calculations. I may change my mind when HydroSHEDS v2 is published.
There are two main differences between higher- and lower-precision mode. The first difference is in the level of detail in the output. If you zoom in on a river centerline or watershed boundary, you can see the jagged lines that come from extracting shapes from these pixels. In low-precision mode, the watershed boundary is simplified, and has fewer vertices. This makes it faster to process and to display.
The second difference has to do with the precision of the watershed boundary with respect to the outlet. In low precision mode, the watershed boundary will not necessarily intersect the outlet point you requested. This is because, in low-precision mode, the app only uses vector data and methods. Your watershed will be assembled from a series of predefined "unit catchment" polygons. These have an average size of around 40 km², or 15 square miles. The boundary will always be some distance downstream of the outlet. For large watersheds, you may hardly notice this discrepancy but for small watersheds, the error can be quite obvious.
In higher-precision mode, the app will try to find a watershed boundary that intersects the outlet point you chose. This requires an extra processing step using raster data and methods. (Raster refers to the use of gridded data.) Raster methods are slower than vector methods and need more data, but they can give more accurate results.
Even in higher-precision mode, the app uses vector methods whenever it can, and only uses raster methods to "split" the most downstream unit catchment. This hybrid method (raster and vector) is faster and more accurate than using either method alone.
New options added in June 2023. Only available in higher-precision mode with MERIT data.
The map data can look rather jagged, a result of being derived from a gridded dataset. By default, the Simplify option is selected, and the app will simplify these polylines. The resulting geodata has fewer vertices, and will download and display more quickly. However, it can still look quite jagged and unrealistic when you zoom in. For big watersheds, you may not even notice. If you want nice smooth lines, you can choose the Beautify option. The following example shows effect of these two different options.
The beautify feature will make the file sizes larger. Loading the watershed will take a little longer and the performance of your panning and zooming the map may suffer (especially on mobile). Please note that the effect is purely aesthetic! It does not make the lines any more accurate! The curves look nice, but they do not necessarily follow the true rivers or watershed boundaries. In fact, they are often a bit further from the truth.
For those interested in the techical details, the code is using the Douglas-Peucker algorithm for simplification. To smooth watershed bounaries, the app uses the Chaikin algorithm, also known as a corner-cutting algorithm. The latter two were fairly easy to add because these functions are included in PostGIS. For the rivers, I'm using a Centripetal Catmull–Rom spline. This was also fairly straightforward to add -- the Wikipedia page has working Python code that I customized slightly. I found that the Chaikin method gave nice looking results for watersheds, and Catmull–Rom was better for rivers. By "nicer" I mean they look more like hand-drawn maps.
By default, the app will display the centerlines of upstream rivers in addition to the watershed boundary.
For large watersheds, the app will not display all the river reaches it found. If it did, the map would be too "busy" and hard to read. Also, showing thousands of rivers on the map could make your web browser slow to a crawl or crash. To show the right amount of detail, the app prunes the river network. The apps shows four orders of rivers, according to their Strahler number. For example, if the most downstream river reach is of order 6, we only show rivers that are order 3 and up. Small headwater streams of order 1 and 2 will not be shown.
Nevertheless, download files (except KML) contain all of the rivers in your watershed that are available from the source dataset, including all the little headwater streams. The files have an attribute named sorder. You can use this field to filter how many rivers to display. In ArcGIS, this is a Definition Query. In QGIS, you can open Layer Properties and use the Query Builder.
You can also use the sorder attribute to set the symbology of rivers (for example, color or line width). I found that it looks nice to set the line width proportional to the square root of the stream order.
The river polyline features have two properties or attributes:
In addition, if you use the USGS data source, river downloads have the fields lenghtkm, and gnis_name. The latter is the name of the river or stream, derived from the US Geographic Names Information System. This is nice if you want to add labels to your maps.
Sometimes the watersheds created by the app are weird or just look wrong. The app does not work that well for small watersheds. The source data is global, and it's not intended for detailed, local applications. If your results look odd, click a slightly different location and try again.
Also, if you're using HydroSHEDS, keep in mind that it is an older dataset, and less accurate in some places, particularly in the northern hemisphere above 60° latitude.
Here is a trick I found for getting reliable results: start by tracing a downstream flow path first, to see where the dataset thinks the river centerline is. Then click somewhere on this line to delineate an upstream watershed. Tracing downstream flowpaths will show you where the river ends and the ocean begins (according to the source data).
You can use keyboard shortcuts to quickly switch back and forth:
If you think there's a bug or something else wrong, please drop me a line at matt@mghydro.com.
When you request a watershed in higher-precision mode, for the app to return meaningful results, it needs to "snap the pour point," or move the outlet to a river centerline in the source dataset. The app will try to automatically relocate the watershed outlet, or pour point, to coincide with a stream channel in the gridded flow accumulation dataset. Finding the right river can be an art and a science. Several algorithms have been proposed for pour point snapping; the algorithm used by the app is a simple one. Getting good results often requires some trial and error. So, if your watershed is not what you expected, click somewhere else nearby and try again.
In lower-precision mode, the app will construct your watershed by merging lots of small "unit catchment" polygons. The app relocates the watershed outlet to coincide with the boundary of a unit catchment. The new outlet may be a kilometer or more from the outlet you requested. For large watersheds, this should not make a big difference. For smaller watersheds, you will usually get better results with higher-precision mode.
The app finds all the "unit catchments" that make up the watershed and merges them together. In geographic information sciences, this is called a dissolve or a unary union. This is usually the slowest step in our calculations. For enormous watersheds (Nile, Amazon, Mississippi, Congo...), it can take a few minutes to merge thousands of little polygons into one big polygon. The good news is, the app only does this work once, and the result is saved and reused (using what programmers call memoization). The next time someone requests the same watershed, or one downstream of yours, it should be very fast. So, the more you use the app to delineate watersheds around the world, the faster it will be (for everyone) in the future.
The rivers can look jagged because of the conversion from a raster, or gridded, dataset to vector polylines. If you're making a map, and you're concerned about appearances, there are a few things you can try. First, if your watershed is in the continental United States, you can try selecting "USGS" as the data source. Their map data is usually quite good.
Second, you can an experiment with the "smooth" and "beautify" options added in June 2023. These won't make the river centerlines more accurate, but they may look nicer.
Finally, you could look for more detailed river data for your maps, for example clipping it to the watershed boundary. For large regions, Natural Earth may be suitable. In the United States, the National Hydrography Dataset is excellent. In Canada, there is CanVec rivers, lakes, and glaciers. You will find many others if you search for "hydrography + GIS + country name" as many countries and regions publish geodata. Otherwise, OpenStreetMap data can be quite good, if inconsistent, and is available globally. You will need to filter the data to select waterways of various types, which can be a little tricky. Luckily, the Yamazaki Lab has done this work already and shared the results: see OSM Water. This dataset is enormous (7 GB, gzipped), so you will probably need to extract a portion in order to work with it in desktop GIS software. It is also a snapshot from 2021, so more up-to-data data may be preferable.
For those interested in more technical details, here are some details on the algorithm that the app uses to delineate watersheds. The method makes use of two distinct classes of data, vector and raster, and uses different methods with each type of data. This "hybrid" method is faster and more accurate than using either type of data by itself.
By way of background, there are many software tools for automated (computerized) watershed delineation. Most methods use gridded terrain data derived from a "digital elevation model" or DEM. To get the most accurate watershed boundaries, you want to use the highest resolution data that is available. For global studies, the current state of the art is to use a DEM with 3 arcsecond resolution (about 90 meters near the equator). Examples include HydroSHEDS and MERIT-Hydro, both of which you can see in use with the app. In the near future, the standard may shift to 12-m resolution, for example with TanDEM-X. And while there are advantages to using higher resolution data, it requires more computer memory and longer processing times.
For an ordinary user without access to a supercomputer, things get complicated when delineating large watersheds. If you want to delineate the basin of the Amazon or Mississippi with high-resolution raster data, you need to load huge datasets into memory. This is beyond the capabilities of most ordinary laptop or desktop computers. Even if you have lots of memory, the processing time can also be very long, on the order of hours for a single watershed.
As an alternative to using large raster datasets to delineate watersheds, one can use a shortcut method with vector data. This is much faster, but less accurate. Vector data is made up of shapes -- points, polylines, and polygons. Examples of vector hydrography datasets are the National Hydrography Dataset (US), HydroBASINS, and MERIT-Basins. The creators of these datasets have already done the work of processing gridded terrain data and creating watershed boundaries. In these datasets, the land surface is typically divided into thousands of polygons referred to as subwatersheds or unit catchments.
To find a watershed upstream of a given outlet location, you search for all the unit catchments that are upstream of the outlet. This can be done efficiently using a network analysis algorithm. Using raster methods, the building blocks for a large watershed are millions of small pixels. By contrast, vector methods use a few thousand polygons, each of which covers a much larger area than a pixel. As a result, processing is usually much faster. In the case of MERIT-Basins, the average size of a unit catchment is 40 km². In contrast, the pixels in MERIT-Hydro are around 0.008 km². Thus, unit catchments are about 5000 times bigger than pixels.
To find your watershed boundary, you merge the selected unit catchments into a single polygon. In geographic science, this is called "dissolve" or "unary union." This operation can usually be done on an ordinary desktop computer.
However, using vector data alone yields imperfect results. The resulting watershed is always going to be a little too big or a little too small, because it is unlikely that the unit catchment boundaries intersect your desired watershed outlet point. For large watersheds, the error may be relatively small, and barely noticeable. This is especially true on a map that is zoomed out to show the whole watershed. But for small watersheds, the error in the watershed area may be unacceptably large. And even for the largest watersheds, when you zoom in on the map to the area near the outlet, the results just "look wrong" because the watershed boundary does not go through the outlet point as it should.
When I was working on this problem, a colleague suggested I try a method that combines both vector data and raster data. With this method, you use vector data and methods for the upper watershed, and raster methods for the downstream portion near the outlet. This "hybrid" method is the best of both worlds since it combines the speed of vector-based methods with the accuracy of raster-based methods.
The hybrid approach is done in four steps once you have identified an outlet location, or point:
In step 3, we use conventional raster-based methods, which are slower but more detailed than vector-based methods. However, we only need to use detailed raster methods on a relatively small area. We open raster datasets (flow direction, flow accumulation) for analysis in "windowed reading" mode. This means we only read into computer memory the portion of the rasters that are within the boundaries of the home unit catchment. Reading a small piece of the raster dataset uses much less memory than reading the entire file into memory.
In step 4, we may optionally remove any internal "donut holes" from the watershed.
I was delighted by the hybrid method I "invented," impressed with its speed, and eager to share it with my hydrologist pals.
I later discovered that the hybrid method for watershed delineation is not exactly new. I believe I have traced its origin back to a 1999 conference paper by Dean Djokic and Zichuan Ye, programmers at the GIS software firm ESRI. They called their method Fast Watershed Delineation, or FWD. They wrote that it was first created at ESRI in 1997 as a set of scripts called Watershed Delineator, "developed for the Texas Natural Resource Conservation Commission, with the sole purpose of efficiently delineating watersheds." Instead of using an existing vector dataset of unit catchments, which I don't believe existed at the time, the scripts create a new set of vectors at runtime using the Arc/Info subwatershed command. While their scripts were in the public domain, they required proprietary software to use them. The scripts are in Avenue, the scripting language for ESRI's ArcView, which the company stopped supporting in 2002.
Since then, this hybrid method has been adopted by the U.S. Geological Service (USGS). Examples include the NHD Watershed Tool for ArcView (circa 2003, ref: USGS), and NHDPlus Tools for ArcMap (circa 2010, ref: Horizon Systems). These scripts use vector data of unit catchments created by the USGS and raster data from the National Elevation Dataset. A limitation of these tools is that they again require proprietary ESRI software, and they are limited to watersheds in the United States.
USGS scientists have also used the hybrid method of watershed delineation in web-based applications. A factsheet from 2000 describes its use on the Massachusetts StreamStats website. This web app was subsequently expanded to the rest of the country; see StreamStats. (Besides watershed delineation, the StreamStats app can "get basin characteristics and estimates of flow statistics, and more.") Further, the hybrid delination method is also used by the USGS for its online programming interface (API) for the National Hydrography Dataset, called the NLDI. Using the API, programmers can access USGS services and data to find watersheds, as well as many other features and data related to rivers, lakes, and streams in the US.
After months of searching online, I was convinced that the hybrid method of watershed delineation had never been described in a peer-reviewed journal article, and had only appeared in "gray literature" such as conference presentations and manuals for defunct software. Finally, I found a discussion of the hybrid method in a 2014 paper in the journal Computers & Geosciences. The authors of this article, Anthony Castronova and Jonathan Goodall from Utah State, described a hybrid method using NHDPlus vector data over the United States. The details of their implementation are somewhat different from what I have done, but it is essentially the same method. Unfortunately, the link to download the code has gone dark, as is often the case with articles more than a few years old. Further, although this paper has been cited in other papers 14 times according to Google Scholar, none of these papers appear to have used or built upon their waterhed delienation method.
In academia, watershed delineation continues to be a somewhat active area of research. Many recent papers are aimed at developing improved algorithms that are faster or more accurate. However, none of the recent papers I found mention hybrid methods. Outside of those working with NHD data in the US, researchers and developers are perhaps unfamiliar with these methods. Although the method is fast and effective, it is poorly documented. Nevertheless, the concepts are straightforward, as it simply involves combining of two well-known methods.
With the publication of my codebase and online demo, I hope to increase awareness of the hybrid method. Another goal is to share open-source code that others can adapt and improve.
My impression is that the app is quite popular with scientists and engineers. And I'm gratified that it has become a useful tool for professionals.
Yet, my main goal in launching the app was related to something called “watershed consciousness.” Knowing where you are in a watershed helps you undersand your place on Earth, and how it relates to plants, animals, and other people. On a practical level, watersheds can help understand where your water supply comes from, and where pollution goes.
This is an old idea rooted in the 1960’s environmentalism and back-to-the-land movement. But I believe it’s still relevant. We all live in a watershed. And we are all downstream of someone else.