Global River Runner

The Global River Runner is a vizualization simulating the path a raindrop would take, assuming it runs off into a stream and from then on to a terminating location, likely an inland water body or the ocean. A running list of interesting flow paths can be found here.

DISCLAIMER

The Global River Runner is an open source Work In Progress, based on open data and open source software components, some of which themselves are in early or alpha development stages (all described in detail below). The vast majority of river paths calculated are based on topographic data collected and processed automatically, and may not reflect true river paths that may be affected by engineered features such as dams, canals, and conduits. Many names of rivers and inland water features such as lakes may be inaccurate as they are based on only on easily available datasets with global coverage. At times, the UI may exhibit slow or otherwise poor performance or encounter other errors. If you find issues regarding any of the above, please submit an issue through Github if you have an account, or fill out an issue survey form, to help us improve the application and underlying data!

Development

The front end visualization was developed by Sam Learner. The back end is developed by Dave Blodgett, Kyle Onda and Ben Webb as a demonstrator of several key aspects of the Internet of Water project, including leveraging open data, open source software, and open standards to create innovative water information products and applications.

Open Data

The “rivers run” by the application are available as a database for download here. This database is a simplification of MERIT-Basins optimized for web viewing, and augmented with river names from the Natural Earth Rivers + lakes centerlines dataset. MERIT-Basins is a global vector hydrography dataset derived from the MERIT-Hydro raster data product, which itself is derived from the MERIT Digital Elevation Model. All of these data are published with an open Creative Commons CC BY-NC-SA License, which allows them to be used for free for science as well as for noncommercial creative works such as this one.

For the river runner application, MERIT and Natural Earth data are combined and processed to include value-added-attributes that enable network navigation. For background, see the add_plus_network_attributes() function from the nhdplusTools R package. For background on the data model that enables this functionality, see: Mainstems: A logical data model implementing mainstem and drainage basin feature types based on WaterML2 Part 3: HY Features concepts

Open Source Software

The back end API is served by pygeoapi, an open-source python server for publishing geospatial data and web-based geoprocessing jobs. The API interacts with the data in a PostGIS/PostgreSQL database. These are all incredibly useful, free and open source technologies for creating spatial data infrastructure that support innovative web applications.

Our API for tracing downstream river flowpaths is documented in the OpenAPI standard here. The code underlying the API is available here.

The basic use of the API is to provide the latitude and longitude of a start point, and you will be returned a geojson file of line segments representing the flowpath downstream on the start point. The format is as below:

https://merit.internetofwater.app/processes/river-runner/execution?lat=<latitude>&lng=<longitude>

For example, trace the path from Humayun’s Tomb in New Delhi, India to the mouth of the Ganges:

https://merit.internetofwater.app/processes/river-runner/execution?lat=28.5827539&lng=77.1890893

The entire API and database stack can be deployed on your own, see the github repository for more details. If you have docker and git installed, it’s as easy as:

git clone https://github.com/ksonda/global-river-runner.git
cd pygeoapi
wget https://prod-is-usgs-sb-prod-publish.s3.amazonaws.com/614a8864d34e0df5fb97572d/merit_plus.sql.gz
docker-compose up -d

Wait some time for the database to load, then point your browser to http://localhost:5050 to explore the pygeoapi server.

Reproducible Workflows

The two source datasets used, MERIT-Basins and Natural Earth Rivers and Lake Centerlines, required integration and processing to make them suitable to the river runner application. The workflow code for this is implemented in the R programming language leveraging a variety of open-source R packages. The workflow is orchestrated by this top-level runner. The workflow automates every aspect of data preparation, from source data downloads to writing input data for the river runner services.

Open Standards

The River Runner API is implemented as a combination of two API standards published by the Open Geospatial Consortium.

The River Runner API is compliant with the OGC-API Processes (OAProc) standard. Development of this standard is ongoing, but it promises to provide a simple, useful framework for URL patterns that allow for the retrieval of metadata describing a given geoprocessing API and executing jobs.

The River Runner API interacts with the underlying database via another API compliant with the OGC-API Features (OAF) standard. This standard specifies simple URL patterns to discover metadata about, and retrieve subsets of geospatial vector datasets. It is the successor to the well-known Web Feature Service.

Prior work

U.S. River Runner

This application is a derivative of the original River Runner, which offers the same visualization for the contiguous United States and was also developed by Sam Learner.

Network-Linked Data Index

The original River Runner relies on the U.S. Geological Survey’s Network-Linked Data Index (NLDI) API, which allows upstream and downstream traces of the US National Hydrography as represented by NHDPlus Version 2. The NLDI is an open system that allows external datasets (such as water quality monitoring stations) to be indexed to the national hydrography. The NLDI itself is derived from the Upstream/Downstream discovery tools of the U.S. Environmental Protection Agency WATERS data system, which indexes many EPA data products to NHDPlus Version 2. The NLDI is developed as an open source project.

Future Work

We may be interested in using the back end we have developed for this project as a starting point to create a service like the NLDI for the entire globe, allowing the indexing and discovery of points of interest that are hydrologically related using up- and downstream search functions. Stay tuned and reach out!