A computer screenshot of JOSM showing OSM building outlines and NAD address points shown for several houses with objects needing address data highlighted in red

What now?

In my previous diary entry I demonstrated using a Tableau visualization to find areas of the United States that could benefit from additional address data. If you find some place you’d like to work on, now what?

Getting set up (social)

OSM is a community project. It’s important to make sure mappers know what’s going and it’s always a good thing to give a heads up about plans for any big data changes in an area. Because this dataset is US centric I’ve been using the OSMUS Slack to keep people up to data about what’s happening. Each state has a “local” channel where you can get feedback and find folks to work with.

Always remember, not everything in the dataset needs to be added to OSM. It doesn’t cost anything to leave stuff out but can be quite time consuming to clean up if not done well.

Getting set up (tools)

Here’s what you’re going to need

  1. Install JOSM
  2. Add the MapWithAI plugin
  3. In the MWAI plugin preferences activate the United States Addresses URL and deactivate any other endpoints (buildings, roads etc).
  4. Add an imagery layer to your view. I used Bing aerial exclusively.

Optionally you may wish to modify the “Address Tag Validator” Map Paint Style by adding:

/* highlight buildings without address */
area[building][!addr:street] {fill-color: #FF0000; color: #FF0000; fill-opacity:1.0}
area[building][!addr:housenumber] {fill-color: #FF0000; color: #FF0000; fill-opacity:1.0}

For some areas, it may be helpful to adjust the Advanced Preference “MapWithAI.duplicatenodedistance”. I found that 15 was helpful for reducing the headache cleaning up duplicate entries for various apartment complexes and other dense areas.

Adding addresses

With all that in place you are now ready. Open the JOSM download dialog, ensure that the datasource checkboxes for OSM and MWAI are checked, navigate the slippy map and download. Et voila! You should now have a view similar to the image at the start.

The MWAI plugin is now ready to do almost all the heavy lifting for us.

The easy parts

For any building highlighted in red, select all address points that are inside the boundary of the building and hit Shift+A. If it’s moving a single node, this will move the tag data to the OSM layer and place it onto the building. For two or more nodes contained in the same boundary, it will simply move them all to the OSM layer.

If there are any addresses on top of buildings that are clearly on imagery, move those to the upload layer with Shift+A.

If there’s an address node for a building that already has address info, delete it from the MWAI layer.

If there’s an address with no discernable building, delete it from the MWAI layer.

The harder parts

Some areas with have address data directly on top of where the buildings are. However, you will also find areas that have nodes needing to be moved. This can be a bit tedious but most of the time it’s still obvious where the address is meant to be.

An address node directly between to houses with no clear indication of which it belongs to

In rare circumstances you will find a truly ambiguous data point. Which house does this belong to? Where did the other houses address go? Neither are knowable from NAD and imagery alone. You have two options: 1. Sort it out from appropriate street level imagery 2. Delete the node from your MWAI layer and let a local mapper sort it out

A building outline with 3 address nodes, two of which are the same

You will absolutely find duplicate address nodes in the National Address Database. The most common, for me, looked like the above. A duplex with two addresses with one of the addresses duplicated into the building center. For this case, you need to delete the extra address in the building center before moving the other two address nodes.

Three buildings with addresses overlaid.

The top building already has address info and one address node from NAD. It can safely be discarded. The bottom building has no address info and two addresses from NAD. Selecting both and using Shift+A will do exactly what we need. However, the middle building has SOME address info tagged on it but there are two addresses from NAD. Because building with more than one address (at least in the US) have addressing as nodes within the building outline, the tags on the building will need to be removed. For this building:

  1. Activate the OSM layer
  2. Select any buildings that have address data but more than one NAD node
  3. Delete the data tags from the building
  4. Activate the MWAI layer
  5. Select the address nodes and merge into the OSM layer with Shift+A

Validation and upload

Once you’ve added enough data for one upload hit the upload button and run the JOSM validation suite. You may wish to fix warnings and errors related to buildings you’ve touched. The most common was overlapping geometry. However, you MUST fix things related to the actual data you are adding. The most common issue for that is “Duplicate address”. Clean them up as you think sensible, with a bias toward removing your addition.

You may find that some of the roadways in OSM do not have streetnames that match the data in addr:street from NAD. This is most commonly because of the roadway missing directionality in the name and is often omitted. However, you will also discover the roadway or NAD have a typo. Or an unexpanded abbreviation. Or just something in complete disagreement. I chose to fix typos and abbreviations, but leave most directionality as was. In cases where it was quite jumbled I left a note for a local mapper to help get things sorted. Occasionally, street side imagery was useful.

Now that the validator is happy hit upload again. Add a nice descriptive comment like “Adding addresses into from the NAD #". Add "esri;National Address Database" to your sources list. Hit upload.


You’ve added some valuable information to the database! Wooooo! Did you find something interesting? Have other questions? Definitely let me know.

I’m hoping to have a few more posts in the near future. Some potential topics:

  1. More odd and ambiguous NAD situations and what to do.
  2. How to set up the Task Manager to share work with other folks.
  3. Using other tools to evaluate your additions and do some Quality Assurance.
  4. How to generate fancy images to show off your hard work.

Login to leave a comment