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 6 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. However, note that some diverted rivers may match this description. Such canals 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 - withdrawn in favor of proposed removal
  • #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 ☑Y fixed as of version 18271
  • #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.

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

☑Y complete as of 27 Oct 2021

South America

☑Y complete as of 21 Dec 2021



☑Y complete as of 4 Jan 2022


☑Y complete as of 11 Feb 2022


☑Y complete as of 18 Oct 2021

Visual Stats

14 June 2022: Annotated pie chart which compares each country's share of waterway=riverbank tags on a global scale. Countries with less than 100 instances of the tag are not labeled.

Global Relative Share of waterway=riverbank Tag

14 June 2022: 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.

14 June 2022: Color-coded world map which categorizes countries and autonomous territories based on the amount of deprecated waterway=riverbank tags they possess. This map was featured in weeklyOSM #585.

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

28 February 2022: Color-coded world map which shows the distribution of deprecated waterway=riverbank in heatmap form.

Map which shows waterway=riverbank objects density tags.

Related Cleanups

Some areas may have additional river-related issues that need cleaned up, or are indicated as a problem when discussing river modernization with the local community. They are discussed in the section below.

Named River Areas

As of 2021-11-04, over 44,600 water=river areas and 8,500 waterway=riverbank areas are combined with a name=* tag. To prevent duplication of names and to comply with the One feature, one OSM element policy, it is desirable to remove the names from these river areas. When doing this, it is highly recommended to check whether a waterway=river way way is present, otherwise the name of the river may accidentally be lost. Also keep in mind that some river areas are actually incorrectly tagged canals, which need to be retagged accordingly.

The following Overpass query can be used to find named river areas:

try it yourself in overpass-turbo
out meta;

Crossing Waterways and Highways

Waterway objects (waterway=river and waterway=stream) should not cross a road without some indication of crossing type, such as a tunnel, bridge, or culvert. In addition, the layer=* tag should be set on either the road or waterway to indicate grade separation.

First, use an overpass query like the one here to identify these crossings:

try it yourself in overpass-turbo
out skel qt;

Run the validator and look for the warning "crossing highway/waterway". If none are found, check your validator settings to ensure this warning is enabled.

As an initial step, run the following search in JOSM to add missing layer tags to bridges:

  1. Ctrl+F to open the find dialog
  2. bridge=yes highway=* -layer=*
  3. Add layer=1 to these bridges.

This will handle the case in which the bridge exists but no layer tagging has been set.

The following search will find underground waterways:

  1. Ctrl+F to open the find dialog
  2. location=underground -layer=*
  3. Add layer=-1 to these bridges and also consider tunnel=culvert if appropriate.

The remainder of the cases will likely need to be handled manually.

See Also

[30] [31] [32] [33]

Discussion of River Modernization during the 2021 OSMF Election

This project was the subject of a community question to the OSMF board candidates during the 2021 OSMF election. Some of the comments from the candidates are excerpted below:

“I have taken part in this mapping project, and I support the river modernization approach. It's not a mechanical edit, merely a targeting mapping campaign by people who want to map rivers & waterbodies well in OSM. I've made some simple scripts to help. We need more of this kind of project in OSM.”

- Amanda McCann

“One group wants to see the water tagged according to the (newer) 2011 proposal, and has reasons for wanting all the 'water' tags to work consistently. They follow a process, document their work, and engage with the local community before modifying the tags, and avoid editing in places where the local community doesn't want their help.”

- Bryan Housel


  1. talk-ca mailing list discussion, April 2021
  2. OpenStreetMap Panama Forum Discussion
  3. OSM US Slack Discussions [3] [4] [5] [6] [7] [8] [9] [10] [11] [12] [13] [14] [15] [16] [17]
  4. OpenStreetMap Austria Forum discussion "River areas modernization"
  5. talk-at River areas modernization
  6. talk-be discussion, July 2016
  7. OpenStreetMap Finland forum
  8. talk-fr discussion, May 2021
  9. A large number of waterway=riverbank polygons are imported stream areas that should either get retraced as ways or tagged as a stream area (natural=water + water=stream). These objects likely require a more targeted approach than outlined here.
  10. OpenStreetMap Germany Forum discussion "Riverbanks"
  11. OpenStreetMap Germany Forum discussion "waterway=Riverbank"
  12. OpenStreetMap Italy Forum Discussion
  13. talk-it mailing list discussion, March 2021
  14. talk-lv discussion, Oct 2021
  15. talk-lv discussion #2, Oct 2021
  16. DWG changeset discussion, Feb 2021
  17. OpenStreetMap Norway forum discussion
  18. Waterway=riverbank only left in Norway
  19. OpenStreetMap Poland forum discussion
  20. talk-pt mailing list discussion, April 2021
  21. talk-es mailing list discussion, March 2021
  22. talk-se mailing list discussion, April 2021
  23. OSM World Discord discussion on river modernization in Sweden
  24. OSM Sweden Facebook group discussion on river modernization
  25. talk-ch mailing list discussion, November 2021
  26. talk-gb mailing list discussion, January 2019
  27. OpenStreetMap India Telegram Discussion
  28. OSM Japan Slack Discussion
  29. talk-au mailing list discussion "River Modernization"
  30. tagging mailing list discussion, Sep 2018
  31. JOSM ticket (open) "Propose to change landuse=reservoir to natural=water+water=reservoir"
  32. iD ticket (closed) "iD is forcing retaging from landuse=reservoir to natural=water+water=reservoir"
  33. Community monitoring of river tagging in Lithuania[18][19][20][21][22]