A web API for delineating catchments globally

Happy World Water Day!

This day reminds us technophiles in the water planning world why we are working so hard on the often times seemingly intractable problem of solving complex water challenges: to help improve the lives of people through better, sustainable access to water. But while tech can seem awe inspiring at times, it can also lead us astray. So in our daily lives working with tech to improve water modeling, we must always ask ourselves: how will this help improve peoples lives, society and the environment?

Our goal with OpenAgua is to develop tools that help inform and solve real water challenges, that are both powerful and easy to use. One path we (and others) are exploring is the use of global datasets to help solve local water management challenges. While many global datasets exist, often they are too coarse or inaccurate for local decision support, or no tool exists to make it easily available in a water planning context. However, there has been a recent confluence of technological innovations that are significantly lowering the cost of developing such tools, in terms of both technical expertise and real cost.

We have recently developed one such tool that has been long envisioned, but only now quite easy to implement: a web API to delineate a catchment anywhere in the world. Though it is currently not quite fully working, it works as a proof-of-concept, and is live.

Demonstration of catchment delineation

I’ll first demonstrate how this API is used in OpenAgua, then explain a bit how it works, and its limitations. First, here’s a screenshot from OpenAgua showing the catchment of the upper Guayllabamba River, Ecuador, delineated using this tool (Quito is in the middle, to the left):

upper guayllabamba
Delineated catchment in the upper Guayllabamba River, Ecuador.

In OpenAgua, to create a catchment like this, simply right-click the outlet of the catchment, and select “delineate catchment here”:

delineate catchment
Catchment delineation menu item in OpenAgua.

The API uses the HydroSHEDS dataset for the delineation. HydroSHEDS is a suite of data from the 2001 Shuttle Radar Topography Mission (SRTM) digital elevation dataset, developed by the World Wildlife Fund. Full disclosure: I personally helped develop HydroSHEDS while working for Dr. Bernhard Lehner at WWF, by manually correcting erroneous streamlines. For this delineation feature to work (and for the API to work generally), the coordinates selected need to be on a streamline as defined by HydroSHEDS. For this reason, in OpenAgua the HydroSHEDS streamlines layer should be shown (more on the streamlines integration in a future post). The use of HydroSHEDS means that this feature (and the API) works up to 60 degrees north. HydroSHEDS spans three resolutions: 3, 15, and 30 arc-seconds. Currently, the web API only supports 15 arc-seconds, which will probably be sufficient for most uses, at least for now.

The use of HydroSHEDS also means an important caveat: it’s not perfect. Having seen first hand the errors inherent in the underlying data, not all rivers are accurate, though I would say for most uses/locations they are. As one example, the following shows the Mapocho River through Santiago, Chile:

mapocho river santiago.png
Mapocho River catchment at Santiago, Chile.

Clearly, HydroSHEDS misses the lower portion of the Mapocho River. But again, this is actually quite rare. (My role at WWF was to spot these errors and correct them. However, I did not work on South America.)

The web API

First off, what is a “web API”? Quite simply, a web API is a web-based tool that accepts commands, does something, and sends back some kind of response, possibly with data (see the Wikipedia article on web APIs). A web API command might look like:


Now, then, what does the catchment delineation web API do, and how does it work? The OpenAgua web API takes coordinates or a set of coordinates and returns data representing catchments flowing into those coordinates.

To delineate the Guayllabamba River at the point Latitude 0.035, Longitude -78.415, the catchment can be delineated with the following web address:


If you copy that then paste this into your browser, you should get back the following:

  "geometry": {
    "coordinates": [
    "type": "Polygon"
  "properties": {
    "fill-opacity": 0.0, 
    "id": "1", 
    "stroke": "#ff0000", 
    "stroke-opacity": 1.0
  "type": "Feature"

This bit of text, in the JavaScript style, or JSON, includes the data needed to represent the upper Guayllabamba catchment (see the coordinates?), as seen in the first figure above. When represented in this way, this data is called “GeoJSON”, which is a specification that most of today’s web-based maps understand. To verify this, you can copy the entire result in the API output and paste it into www.geojson.io. Or, you can see it here.

Even more detail

If you are interested in the technical nitty gritty, the code is open source, at https://github.com/OpenAgua/catchment-delineation. There are no secrets here, and the routines are fairly basic, similar to what a budding hydrologist would learn in Hydrology 101. If you are a developer or grad student, feel free to contribute, or use the code yourself.

In actual usage, there are some important limitations, which you can read about here. Despite the limitations, the API itself is fairly robust. It is hosted on Amazon’s Amazon Web Services, deployed using Elastic Beanstalk.

Last thoughts

The use of web APIs is growing, and can be of strategic value to companies. With this particular web API, currently in its infancy, we allow anybody to delineate a catchment, anywhere in the world. As OpenAgua grows, we hope to offer many more similar functions to the global water resources planning community.

Catchment delineation is an appropriate first step for OpenAgua in providing an API, as they are essential not only to simulating runoff in data-poor areas, but also for understanding water geography generally. A solid understanding of water geography is itself the first step to improving water management everywhere and the lives that depend on it.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s