From OpenStreetMap Wiki
Jump to: navigation, search

If you want to start importing GRB and CRAB data, YOU MUST READ THIS WHOLE PAGE VERY CAREFULLY and follow its instructions. If you fail to do so, you might miss important instructions resulting in your access to the tool to be revoked, or worse.

Red x.svg To do: translate this whole thing to Dutch if the import is approved

Red x.svg To do: i probably missed some major things, so try to think out of the boxM!dgard [ talk ] 20:27, 31 January 2018 (UTC)


Welcome to the GRB and CRAB import instructions. Please understand that importing is a complex job that is subject to higher standards than the rest of OSM. You should only consider joining any import effort if you have a decent amount of experience as a mapper in general, and with JOSM in particular.

This import is not rushed. There's no deadline. We're never going to do quantity-based rankings of importers. Please focus on data quality rather than speed. We're not merely copying the GRB in OSM, we're building upon it to create data that is actually better than the GRB.

It's advisable to start in a nearby area so you might be able to go for a survey if need be.

If you have any problem understanding this guide, do not be afraid to ask for help. The Belgian Matrix room Matrix-messaging-logo.png and IRC channel #osmbe are bridged, so you can ask for help on either one. Alternatively you can send a private message to User icon 2.svgM!dgard (on osm) or User icon 2.svgGlenn (Glenn Plas on osm).

We're also organizing meetups in real life to get familiar with this import! You are warmly invited to participate in at least one of them. We can give you tips and instant feedback. Red x.svg To do: how to know when there's a meetup


You will need:

  • JOSM and experience with it
  • the SimplifyArea plug-in for JOSM
  • the utilsplugin2 plug-in for JOSM

Red x.svg To do: method to subscribe to updates about the instructions


Red x.svg To do: do we need a separate account?

To get started, you have create a dedicated account for the import. A good choice is to take your existing user name and append _GRB to it.

You will need a second e-mail address because the OSM site requires addresses to be unique. On some email providers, like Gmail, you can create aliases by just appending +something to the user name part of your address, e.g. You don't need to configure this, it just works.

Set up JOSM

Red x.svg To do: instructions for remote control

Red x.svg To do: instructions for historical imagery

Export data from GRB

  • Open JOSM.
  • Go to the GRB import tool at and log in using your OpenStreetMap account.
  • Zoom in on the area you want to work on.
  • Retrieve the GRB buildings that already exist in OSM (currently a button).
  • Filter layers to take a cross-section (currently a button, will be automated).
  • Open the area in JOSM (button) and load the GRB buildings JOSM (currently yet another button that will disappear in the future).

Red x.svg To do: talk about desired changeset size (and hence export size)

Conflate data

In the end, you are responsible for the data you add.

Red x.svg To do: add good/bad screenshots

For each object you are importing

  • If the object is already drawn:
    • If you want to use the GRB version, use the Replace Geometry tool.
    • If you want to completely keep the OSM version, just copy the tags from the GRB exported object and delete the latter.
    • If you want to keep some parts of the OSM object and some of GRB's, you can do so like this: Red x.svg To do: create screenshots and screencast.
  • Check the tags. Determine the building type, do not rely on the default:
    • Use street-level imagery if available.
    • Use aerial imagery.
    • Use your common sense: be aware of the environment and any POI that's mapped in or on the building.
  • Make sure the object is properly connected to existing objects where applicable, in particular other buildings. Red x.svg To do: what to do with landuse if building is adjacent to it? Merge to building or keep separate?
  • Use the Simplify Area operation (Ctrl+Shift+Y) if the building appears to have too many nodes.
  • Red x.svg To do: add instructions for building=verdieping, the tool will probably export this tag as-is and it requires manual fixes: in some cases it is best to merge it with the main building and drawing a road with tunnel=building_passage underneath, in other cases one should use building:min_level=*, but it might not be always building:min_level=1 so a survey should be done, street-level imagery should be consulted, or a fixme=* should be added
  • Red x.svg To do: add other instructions?
  • If you encounter strange tags, like for example building=gebouw omlijnd met virtuele gevels or building=tuinhuis, contact us. These should not be there.

Red x.svg To do: let the tool analyze building types to check for anomalies?

Watch out

  • Conflating means merging with existing data. You might be tempted to just remove existing objects and drop the GRB ones in OSM, but don't ever do that! Delete as little existing OSM objects as possible.
  • You might be tempted to remove buildings that aren't in the GRB. Only do this when you are sure the building really does not exist. It may be not included in the GRB because it's a new building, or a small shed for which no building permit was needed. Use different sources to determine what to do: old aerial imagery of different years is very useful to see the history of the place. Of course doing a survey would be perfect. If you're not sure, leave the building in OSM and add a note.
  • The GRB is not perfect. Moreover, the ground truth always prevails.
    • Some buildings in the GRB have separate addresses but are just one GRB building. In OSM those may be mapped separately if the addresses are clear. Both buildings should get the same GRB source tags.
    • The inverse is also possible: some buildings and bridges are mapped separately in the GRB but may make more sense in OSM as one building. Merge those using Shift+J. For the GRB source values, you can merge the values of both objects (select "all" in the tag merge conflict dialog). Red x.svg To do: screenshot
    • Only parts of buildings that are visible from the public roads are measured by surveyors in the GRB, the rest is drawn from aerial imagery. If building parts that are not adjacent to the road look more correct in OSM than in the GRB, keep the OSM version for that part of the building (tutorial linked above).
  • Keep the source:geometry:*=* tags that the tool exports. They let the tool detect that the building was imported and also allow for updating the building in the future. If you didn't use GRB's geometry, you can remove the source=GRB tag. Red x.svg To do: is the tool going to continue adding this tag?

Workflow tips

Red x.svg To do: make sure to explain every action's effect on history

Checking if an object already exists in OSM

To preserve as much history as possible, it is useful to be able to find out whether an object already exists in OSM or it is new. To do this, you can press Ctrl+I and look at the number on the first line. If it's a positive number the object already exists, and you shouldn't just delete it without good reason. If it's negative (having a minus sign) it only already exists in your editor and it's no problem to delete it.

Alternatively, you can request an object's history with Ctrl+H. If the object exists, you will see an overview of its history. If it doesn't, you will get a popup saying you should select an already uploaded object to view history. If the object exists, loading the history might take a while, that's why we recommend the Ctrl+I approach, but you might find the Ctrl+H method a bit clearer. Both methods always produce the same answer, so you can choose.

When you upload your changes, all objects with a negative ID will be added to OSM, and thus get a positive ID.

Tagged nodes on an existing building

Replace Geometry will not work if there are tagged nodes on the building. Fixing this while at the same time retaining the history of all objects is desirable and not difficult. Simply snap the nodes onto the new building, and Replace Geometry will work. Red x.svg To do: screenshots+screencast

Merging and splitting buildings

You can split areas by drawing a split way and pressing Alt+X. The larger one of the parts inherits the history. Red x.svg To do: screenshots+screencast

You can merge two connected areas with Shift+J. If there are conflicting tags, you will get a popup to consolidate the tags. For the source:geometry:*=* tags, you can choose 'all'. Merging areas is equivalent to consolidating the tags, and then adjusting the geometry of one area and deleting the other. So if both objects already exist in OSM, you are effectively deleting one. Red x.svg To do: screenshots+screencast

After you're done with the objects

  • Run JOSM's validator on the data and resolve issues with your data.
  • Upload the data.

Complete addresses with CRAB

Address data in the GRB is copied semi-manually from the CRAB, so it's not always correct or up-to-date. Therefore, check the imported buildings with the CRAB. If you're not sure, go survey or leave a note.

  • After uploading the GRB buildings, wait a minute or two. (This is to make sure the Overpass data is updated and contains your new buildings.)
  • Go to the CRAB import tool at
  • Red x.svg To do: write instructions on how to check addresses with CRAB data

You can now start working on a new area.