WikiProject Waterways/River modernization

From OpenStreetMap Wiki
Jump to navigation Jump to search

Read this First

5 March 2021: I started this page as a way to document and track river and stream cleanup in the United States. My edits using this procedure in the US are discussed with local mapping communities as required by the Automated Edits code of conduct. Mappers in other countries have found this procedure useful and have since expanded the page to track areas outside of the United States. I welcome this collaboration. If it is useful to you, feel free to use the "progress" section to track progress in other places. If there is an issue with a particular changeset associated with this procedure, please comment on the problem changeset, and discuss the issue with the mapper that created it.

--ZeLonewolf (talk)

River Modernization Project

The River Modernization Project aims to track and modernize river tagging worldwide while fixing geometry and tagging errors on rivers and streams. There are many issues such as overlapping water areas, mis-tagged tunnels and culverts, node/way duplication, legacy tagging schemes, and common tagging errors, which can be quickly identified and fixed via the JOSM validator using sparse-editing techniques. In addition to fixes to the map, this project's focus on river and stream tagging specifically has led to the identification of 11 bugs in JOSM and its validator of which 5 have been fixed so far.

Please be aware of the Automated Edits code of conduct; large-scale edits should only be done with the consent of local mapping communities.

Background on River Tagging Schemes

The earliest OpenStreetMap tagging schemes for rivers had two tags: waterway=river for the tagging ways representing the path of the river, and later waterway=riverbank, which was used to tag the banks (edges) of the river. This tagging system evolved over time, and mappers began connecting the two riverbanks into closed polygons, and today waterway=riverbank is used to tag the areas of rivers. This evolution resulted in a confusing situation in which the riverbank tag was really used for the river area.

In 2011, the proposal water details was approved, creating the water=* key, which provided additional detail to areas tagged natural=water. That proposal approved the new tag water=river (+natural=water) as a wholesale replacement for the older waterway=riverbank. However, since water=* was brand new, the proposal recommended dual tagging for a period of time in order to allow data consumers and renderers to catch up.

Over time, water=* became increasingly popular and by mid-2016, mappers began consistently favoring the use of water=* over older schemes.

On December 11, 2018, a new issue was opened in the iD editor's issue tracker to change that editor's presets to use the water=* scheme rather than competing alternatives. This change took effect with version 2.13.0, released Jan 23, 2019. A few months after this iD editor preset change, mappers began consistently favoring the use of water=* in much larger numbers.

In the 10 years that has passed since water=* was approved, natural=water has become universally accepted by data consumers and map renders. In order to standardize water feature tagging across the database, and maintain alignment with the standard iD editor, the following procedures are provided as a guide to mappers wishing to modernize river tagging in their area.


This page documents the process of modernizing river tagging, resulting in river areas passing all JOSM validator checks and tagged with natural=water + water=river instead of waterway=riverbank.

Step 0 Ensure that you have the support of the local mapping community. Also, it is recommended to upload changesets periodically for a large modernization job.

  • See the OSM Community Index to learn where the local mapping community can be contacted in a particular area.
  • Here is a suggested message for reaching out to a local OSM community:

I'm working on a project that aims at improving the river data in OSM. The main aim of the project is fixing various issues like duplicated nodes, overlapping water areas, crossing ways, and using the newer natural=water + water=river scheme instead of the older waterway=riverbank. Would you support such a project in order to fix geometry errors and update tagging on <location>'s rivers? You can learn more about this project and what exactly is being done here. Let me know if you have any questions.

Step 1 Sparse-load unspecified water areas into JOSM.

The purpose of this step is to fix tagging on river water areas that are tagged natural=water but are missing the water=river tag.

It is recommended that this step be done with the Carto "Black and White" imagery set. The query below is used to load water data into JOSM using the "Download from Overpass API" option. The "geocodeArea" option can be changed to whichever area is being worked on. This can be a state, county, etc., as needed.

try it yourself in overpass-turbo
{{geocodeArea:"Rhode Island"}}->.a;
out skel qt;

Alternately, use a bounding box:

try it yourself in overpass-turbo
{{geocodeArea:"Rhode Island"}}->.a;
out skel qt;

Once these are downloaded, you will probably have to filter out many smaller objects to "see" likely river objects. Press Ctrl + F and search for something like natural=water areasize:-5000. This will search for small objects in the downloaded data set. Once this selection is made, be sure to add the members of selected relations to the selection (select selected relations, right-click, "Select members (add)"). Press Ctrl + Shift + P to purge these objects from the editor. Repeat this process, each time increasing the areasize parameter until the smaller objects have been purged and just rivers are remaining.

Once you've purged out the minor water features, tag the remaining natural=water objects with the missing water=* tags, such as water=river, water=stream, water=reservoir, water=lake, etc as appropriate. Be sure to upload your changes!

Once you've completed the tagging of these water areas, press Ctrl + F4 to purge this layer. Be sure to leave enough time for Overpass to updates (i.e. at least 5 minutes) before starting the next section.

Step 2 Sparse-load rivers into JOSM.

Next, change the query to download all river features, and upload

try it yourself in overpass-turbo
{{geocodeArea:"Rhode Island"}}->.a;
out skel qt;

Alternately, use a bounding box:

try it yourself in overpass-turbo
{{geocodeArea:"Rhode Island"}}->.a;
out skel qt;

Step 3 Canal search

Visually scan for canals mis-tagged as rivers. They are usually identifiable by their geometric, rather than natural shapes. They may appear in large clusters in agricultural regions. Canal water areas should be tagged natural=water + water=canal.

Step 4 Pre-validation

Run the JOSM validator and fix all errors. Common errors include:

  • Geometry errors (overlapping, unclosed, duplicate nodes, relation role problems, members with parent tagging)
  • River islands that should be islets
  • Tunnel and culvert tagging issues

Handling duplicate nodes

  1. If there are large numbers of duplicate nodes, see if they are the result of duplicate ways. If so, address the duplicate ways.
  2. If you encounter a bad import of streams with many duplicate nodes at the endpoints, save the layer as an OSM file.
  3. Edit the OSM file and manually add in a bounds line to trick JOSM into thinking the area is downloaded. Make the lat/lon values sufficiently large to cover the problem area. Example:
    <bounds minlat='25.6341203' minlon='-130.0554485' maxlat='55.6348159' maxlon='-70.054558' origin='CGImap 0.8.3 (1448173' />
  4. Save, re-open in JOSM
  5. For each validator warning block for duplicate nodes, double-click the category to select all duplicated node sets. Press Ctrl + Alt + D to download referrers. Press the "Fix" button to merge duplicate nodes. Using this process will avoid upload conflicts.
  6. Upload the duplicate node fixes.
  7. Save the OSM file, remove the bounds line, and reopen it in JOSM to resume where you left off.

Step 5 Resolve conflicting natural=* and water=* targets

There may be rivers which have conflicting tagging which would prevent automatic conversion.

  • Press Ctrl + F and search for waterway=riverbank. Find natural in the tag inspector, double-click, and expand the value pull-down (see image below). This will tell you what values are currently in use for natural=* (other than natural=water, which is non-conflicting) on features tagged waterway=riverbank.
Natural listing.png
  • For each of these values, do a new Ctrl + F and search for waterway=riverbank natural=<value>. Manually inspect each of these objects and resolve the conflict.
  • Repeat this process for the water=* key. For example, if an area is tagged water=reservoir and waterway=riverbank, decide whether it is a reservoir or a river area, and update the tagging accordingly.
  • In addition, search for areas that are mistagged as other types of waterway e.g. waterway=river with type:way closed waterway and fix those as well.
  • Be sure to upload your changeset before proceeding to the next step!

Step 6 Upgrade tagging

  • Press Ctrl + F and search for waterway=riverbank
  • Delete the waterway=riverbank tag from the selection
  • Set natural=water and water=river

Step 7 Post-validation

  • Re-run the JOSM validator and resolve any new errors which have occurred from the conversion. Note that JOSM reports different findings from adjacent water=river and waterway=riverbank objects as it does from adjacent river areas with the same tagging, so new issues may appear in this second round of validation.

Related JOSM Bugs

Below are JOSM bugs that were discovered and reported as part of this project:

  • #20352 Incorrect validation warning on waterway crossing of adjacent water areas ☑Y fixed as of version 17447
  • #20569 False positive on wash trails reported 6 Mar 2021
  • #20570 waterway=riverbank handled differently from natural=water + water=river in validator overlap findings ☑Y fixed as of version 17653
  • #20591 Rename "Riverbank" preset to "River area" reported 12 Mar 2021
  • #20663 Area style on outer way not flagged when different river area taggings are combined reported 24 Mar 2021
  • #20664 False positive finding on wall areas mapped as multipolygons reported 25 Mar 2021
  • #20674 Water area inside water area not detected for waterway=riverbank ☑Y fixed as of version 17680
  • #20681 Unnecessary tag area=yes not reported for waterway=riverbank reported 28 Mar 2021
  • #20690 Changeset comments off-by-one error ☑Y fixed
  • #20707 Tunnel on suspicious object not thrown for riverbank reported 2 Apr 2021
  • #20754 Unusual Unicode character on Nuu-chah-nulth language characters ☑Y fixed as of version 17766


Note: this section is a collaboration of mappers working worldwide. This is not a list of areas that I have personally modernized.

See Taginfo map of waterway=riverbank instances.

Use this Overpass query to enumerate the number of OSM elements with the waterway=riverbank tag:

try it yourself in overpass-turbo
out count;

North America

South America





☑Y complete as of 18 Oct 2021

Visual Stats

20 October 2021: Annotated pie chart which compares each country's share of waterway=riverbank tags on a global scale. Countries with less than 400 instances of the tag are not labeled.

Global Relative Share of waterway=riverbank Tag

20 October 2021: Color-coded world map which categorizes countries and autonomous territories based on the percentage the modern water=river tag accounts for all of the country's river area tags, including waterway=riverbank. Countries with a 100% rating use water=river exclusively, while those with a 0% rating use waterway=riverbank exclusively.

Map which color-codes OSM river modernization progress based on prevalence of waterway=riverbank and water=river tags.

20 October 2021: Color-coded world map which categorizes countries and autonomous territories based on the amount of deprecated waterway=riverbank tags they possess.

Map which color-codes OSM river modernization progress based on volume of waterway=riverbank tags.