Global Watersheds App – Help / About

Credits

Created with global data from MERIT-Hydro, MERIT Hydro-Vector, and HydroSHEDS.

Citation

If you use this in any published work, for now you can cite the GitHub repository using the Zenodo DOI:

Heberger, Matthew. delineator.py: fast, accurate global watershed delineation using hybrid vector- and raster-based methods. 2022. https://doi.org./10.5281/zenodo.7314287

Contribute

If you found this web app fun or useful, consider making a donation to one of the charities that I help to manage, Build a School in Africa to build schools in Mali, West Africa, or The Dokotoro Project, to distribute health information in African languages.

Terms of use

There is no guarantee of 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. That said, if you use this for a cool project, I'd love to hear about it.

Code

I have released open-source code for doing watershed delineation on your own computer with Python. Visit: https://github.com/mheberger/delineator

Downloads

If you want to download geodata of your watershed or flowpath, first check the "Make downloadable" box under options, then create a new watershed. Any new watershed you make while the box is checked will be saved on the server and ready for download.

Three download formats are available:

API (experimental)

I've set up an API so you can get watersheds even if you're not using the web app. You just need to provide a carefully formatted URL. There is a separate link for watershed boundaries and for rivers. It will return a GeoJSON string that many applications can use. To use it, you need to provide the latitude and longitude of a watershed outlet, and tell it if you want high-precision or low. (Note that if your watershed has an area of over 50,000 km², the app will revert to low-precision.)

As when you are using the regular web app, it can take a while for the app to create large watersheds.

This feature is experimental and subject to change! Drop me a line and tell me if you are using it for something cool.

Base URLs:

        https://mghydro.com/app/watershed_api 
https://mghydro.com/app/upstream_rivers_api

Parameters

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"

Examples:

        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
    

Usage

With the API, you can plug the URL right into QGIS. Choose Layer > Add Layer > Add Vector Layer, then and in the field, "Vector Dataset(s)," add the URL, then click "Add." Adjust the styles, and you can have something that looks like this:

Screenshot of QGIS showing the watersheds API in use

Origins

In the course of my research in hydrology and remote sensing, I needed to delineate hundreds of watersheds. I needed a routine that is fast and accurate, and I wasn't happy with any of the existing software that I tried.

There are many software tools out there for automatic watershed delineation, nearly all of which use gridded terrain data -- a digital elevation model or DEM. But things get complicated when you're dealing with large watersheds. To get good results, you want to use the highest resolution data that you can find. For global studies, the current state of the art is 3 arcsecond resolution, or about 90 meters near the equator. The problem is, when you try to delineate a watershed the size of the Amazon or the Mississippi with high-resolution data, you need a supercomputer.

As an alternative, you can use vector data from a a dataset like HydroBASINS or MERIT-Hydro-Vector. The creators of these datasets have already done the work of creating watersheds from gridded datasets. These vector datasets divide up all the Earth's land surface into lots of little shapes called unit catchments. To find your watershed, you look for all of the unit catchment polygons that are upstream of the point you are interested in (using an efficient network analysis algorithm) and merge them together. Instead of using pixels as your building blocks, you use polygons, which have an average size of 40 km².

However, the resulting watershed is always going to be a little too big or a little too small. For large watersheds, the error is small compared to the size of the watershed and may be unnoticeable. But for small watersheds, the errors can be significant, and the results will not look right.

A colleague suggested trying a method that combines vector data and raster data. I coded it in Python, and I was delighted by how well it worked. It was much faster than other methods I tried, and does not require a supercomputer for large watersheds.

So I wanted to share it with the world. As far as I can tell, there are no other (free) websites that help you delineate a watershed anywhere in the world. I hope you enjoy playing with the watersheds app. I am endlessly fascinated by clicking on different places around the world, and seeing where water comes from and where it's going. I hope you have as much fun playing with it as I do!

Inspiration

I spent a lot of time searching for an app that delineates watersheds, and was surprised that one like this did not already exist. However, I found some other cool sites:

Problem areas

In my experimentation, there are a few places where the watershed delineation results are not very good. This occurs over terrain that is flat, or hydrologically complex, or both. For example, there may be irrigation canals or pipelines. Another problem area is river deltas, or branching or braiding rivers. The input datasets do not attempt to represent distributaries, where the flow in a river splits or fans out.

Some examples are:

Missing Data

Unfortunately, neither MERIT-Hydro nor HydroSHEDS has data for some of the smaller islands. The biggest gap in my opinion is Hawaii. I'm not sure why the creators of these datasets did not include these data. However, there is data for some islands, and you'll be able to delineate watersheds on Fiji, Tuvalu, the Galapagos...

Trace upstream or downstream

Choose one of two options: "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.

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 eventually flow towards the watershed's outlet. So knowing the watershed for a point on a lake, river, or stream can tell you where the water came from. Watersheds are extremely important in hydrology and environmental science, for everything from studies of flooding, water pollution, 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).

Low-precision vs. high-precision mode

The app uses high-precision mode as the default, as long as you are zoomed in far enough on the map (level 9 or higher) and have chosen MERIT-Hydro as the data source.

There are two main differences between high- and low-precision mode. The first has to do with 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. Oftentimes, the dataset has more detail than we need, especially if you're making a map of a large river basin. And when you try to display a map of such detailed features in a web browser, it can be very slow to render. In low-precision mode, the watershed boundary has been simplified, and contains fewer vertices. This makes it faster to process and to display.

If the app finds that your watershed has an area over 50,000 km², it will revert to low-precision mode.

The second difference has to do with how accurately the app tries to find the watershed boundary near the outlet. In low precision mode, your watershed will be assembled from a series of predefined unit catchments polygons, each with an average size of around 40 km², or 15 square miles.

This is usually good enough for large watersheds and is relatively fast. However, the watershed boundary will not be coincident with the outlet point you requested. Rather, the boundary will always be a bit downstream of the point. For large watersheds, you may hardly notice this discrepancy but for small watersheds, the error can be quite obvious.

In high-precision mode, the app will try to find the watershed boundary that goes through the outlet point that you clicked. This is an extra processing step that uses raster-based method and gridded data. This method is slower and more computationally intensive, but gives more accurate results.

Instead of using this more detailed method for the whole watershed, the app will only use it for a small area, the most downstream unit catchment. It merges this result with upstream catchment polygons that have been precomputed and stored efficiently in vector format. The combination of vector and raster methods is what makes this app different from other watershed delineation routines.

Note that high-precision mode is only available with MERIT-Hydro data. I did not bother to implement it for HydroSHEDS. While HydroSHEDS is an excellent dataset, and has a lot of features that make it very nice to work with, I don't think it is accurate enough to justify creating high-precision mode. I may change my mind when HydroSHEDS v2 is published.

For large watersheds, the app may not display all the river reaches from the source dataset. The app shows four levels of river reaches by stream order, or Strahler number. For example, if the most downstream river reach is of order 7, we only show streams that are order 3 and up. Small headwater streams of order 1 and 2 will not be shown. Otherwise, the map would have too much detail, and your web browser might struggle to display them all.

Nevertheless, if you choose to download a shapefile or GeoJSON file, the downloaded file will contain all of the rivers from the source data, including all the little headwater streams. The files have an attribute named sorder that you can use this to filter the results or to set the symbology if you are making a map. I found that setting the line width proportional to the square root of the stream order looks nice.

The river polyline features have two properties or attributes:

What if your results are odd?

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 really not meant for detailed, local applications. If your results look odd, click a slightly different location and try again.

Here is one trick I found for getting good results: start by tracing a downstream flow path first, to see where the dataset thinks the river centerline is. Click somewhere along this line to delineate an upstream watershed. It is also useful for seeing where the dataset thinks the river ends and the ocean begins. You can use the keyboard shortcuts to quickly switch back and forth (d or f for downstream flowpath, and u or w for upstream watershed).

If you think there's a bug or something else wrong, please drop me a line at matt@mghydro.com.

Why does the app show two different watershed outlets?

When you request a watershed in high-precision mode, the app needs to "snap the pour point" to a river centerline in the source dataset in order to return meaningful results. The app will try to automatically relocate the watershed outlet, or pour point, to be coincident with a stream channel in the gridded flow direction dataset. This is an inexact science, so if your watershed looks weird, click somewhere else nearby and try again.

Why does it sometimes take a long time to delineate a watershed?

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 step is often the rate-limiting step in our calculations. For enormous watersheds (like the Nile, Amazon, Mississippi, Congo...), it can take a few minutes. The good news is, the app only does this work once, and the result is saved and reused (what programmers call memoization). The next time someone requests the same watershed, it should be very fast. So the more you use this app to delineate different watersheds around the world, the faster it will be in the future.

Why do the rivers look unrealistic when I zoom in?

The river polylines can look jagged because of the conversion from a raster, or grid-based dataset. If you're making a map, and you're concerned about appearances, there are a couple things you can try. GIS software has routines that can help you smooth out these jagged lines, and make them more curvy and aesthetically pleasing. For example, in QGIS, open the Processing Toolbar, and search for "Smooth" or the GRASS tool "v.generalize". Note that the lines will end up with more vertices. With some trial and error, you can use "simplify" and "smooth" to improve the appearance of the rivers. They will not be more accurate, but they may help you make pretty maps!

You can also look for more detailed 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 can probably find others if you search for "hydrography + country name" as many countries and regions publish geodata. Otherwise, OpenStreetMap data can be quite good. 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 and shared the dataset: see OSM Water. However, the 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.