From OpenStreetMap Wiki
Jump to: navigation, search

Project Brief

Our goal is to map the suburb of Epworth in Harare, Zimbabwe, for the Missing Maps Project. Data collection for the area, including road networks, landmarks used by local people to navigate, admin areas and unofficial 'neighbourhoods' (again used by locals to navigate). To register the community, and to provide accessible records for the function of infrastructure management, water supply and sanitation needs. Original OSM Task:

Further, we hope to introduce the advantages of Open Street Mapping to the local community. To consolidate a team of volunteers from the local areas to carry out this task, drawn from MSF Local (National) Staff and members of the Local Administrative Board (mainly Council Engineers), and to strengthen working relationships between humanitarian and local parties.

Date March, 2015 ongoing

Project Managers Kieran O'Sullivan (Humanitarian OpenStreetMap Team), Rupert Allan (Medecins Sans Frontieres), Pete Masters (Missing Maps Project).

Why map Epworth?

Epworth is a large community to the south-east of Harare, the capital of Zimbabwe. We are mapping in order to provide more information about the local water & sanitation infrastructure and to provide a detailed map to enable better community organisation and planning.

Epworth has a different addressing system from most regions. Instead of sequential numbers along a road, each plot has a unique number within Epworth. Therefore, you may need to get to 8143 Epworth, but it is very difficult to know where that is unless you are well-acquainted with this idiosyncratic system. By adding the numbers to the plots, it makes them searchable. This is very useful for NGOs who may wish to find a particular address quickly and efficiently. MSF's work in Zimbabwe is described in their 2014 Activity Report.

If you want to see what Epworth looks like on the ground, you can check out Mapillary's paths.

How to get started with Epworth Field Papers

This page should have almost all of the information you require in order to start transferring information from the field papers to OpenStreetMap. Please leave feedback in the 'talk' section - we want to make this as easy to follow as possible!

These are the main steps:

  1. Learn how to map
  2. Download the Field Papers for JOSM plugin
  3. Choose a tile to work on
  4. Download the information for the tile
  5. Download the residential building preset
  6. Upload the map to Field Papers (not always necessary)
  7. Load Bing, OSM data and the field paper into JOSM
  8. Start mapping
  9. Upload and record progress

These steps are shown below in a tutorial.

Quick Links

Field Papers for JOSM plugin

Tile completion record

Dropbox folder

Field Papers






Getting Started

This section explains how to set up the various layers for field paper mapping in Epworth, doing the mapping itself, and then recording your activity.

Download the Field Papers plugin

You will only have to do this once.

1. Open JOSM

2. Go to ‘Preferences’:

a. In Windows either press F12, open ‘edit\preferences’ or press the preferences button on the toolbar at the top:

JOSM Images preference.png

b. In iOS, click on ‘JOSM’ in the top left of your screen and select ‘preferences’

3. Click on the ‘plugins’ button

JOSM plugin.png

and click ‘Download list’ at the bottom.

In the search bar at the top, type ‘fieldpapers’ and the list should now only show one plugin:

Field Papers in Plugins.JPG

4. Tick the box next to field papers, and click OK at the bottom of the preferences box. You will be asked to restart JOSM; do this.

OK Cancel Help.JPG

Install the Visual Tags preset

You will only have to do this once.

1. With JOSM open, download any part of the OSM data set using Here, it's centred around MSF UK's HQ:


Click on the down arrowhead to the right of 'Edit' on the top toolbar of OpenStreetMap; you will get a menu as shown in the picture above. Click on Edit with Remote Control (JOSM or Merkaartor). This should open the area in JOSM. (This stage is necessary to activate the Presets menu.)


2. Download the Residential Preset from here: Epworth Preset to any directory on your computer - just make a note of where it is.

3. Back in JOSM, open the Presets menu from the toolbar at the top of JOSM, and click on Preset Preferences. You should get a window looking like this:


On the right hand side, next to the Active Presets, there is a + (add) sign. Click this, and you will get a box asking you to add a name and a URL or filename. You can put whatever name you wish - something descriptive like 'Epworth Residential' may help you remember what it's for. Next, click on the file icon to the right of the URL/Filename box. Select the Epworth Preset (...571.xml) file you downloaded in step 2. It should now look something like this:


Click OK, and then click OK on the Preset Preferences box. You'll be asked to restart JOSM again - do this. Next time you open JOSM and have some OSM data open, you should be able to see the preset loaded into your presets menu:


Choose a tile to work on from the Tile Completion Record

Tile completion record

The tiles have been split into four quadrants (NW, NE, SW, SE) and are then referred to by a typical letter-number system, where letters refer to location on the East-West axis and numbers refer to location on the North-South axis.

Choose a red or yellow tile from the spreadsheet below, and take note of the tile code (e.g. E5) and quadrant (e.g. SW). Change the colour of the cell in the spreadsheet to pink so that other people know you're working on it - don't forget to change it back yellow or green after you've uploaded your work!

Download the tile information

In this tutorial, we will show you tile NW F8.

1. Open the Dropbox folder.

Epworth Dropbox.JPG

2. Choose the relevant region. In this case, it’s NW.

3. Next, open the ‘pack’ for your chosen square. There should be a number of files in here.

Map Survey in Dropbox.JPG

It is easier to identify the relevant ones if you change the view to list mode using the right hand button.

Dropbox list toggle.JPG


  • If the Field Papers code was not included in the spreadsheet: Download the image map (listed as the square’s name, i.e. F8.jpg here) and any relevant surveys. There’s only one survey image here, F8 Survey.jpg. Then move on to the next section: Upload the map to Field Papers.
  • If the Field Papers code was included in the spreadsheet: Download only the relevant survey files. In the example tile there is only one, F8 Survey.jpg. Skip the Upload the map to Field Papers section and move straight on to Load the layers into JOSM.

Upload the map to Field Papers

1. Open and click on Upload. You should get this screen:

Field Papers Upload Page.JPG

2. Click on ‘Choose Files’ and select your map file (in the example case, it is F8.jpg). You’ll get a screen like this:

Field papers Uploading.JPG

Which will change automatically to this:

Field Papers Processing.JPG

The processing might take a while depending on the number of people using the website. Eventually, you will get a page looking like this:

Field Papers Processing Complete.JPG

Note that although this is a NW sheet, it says ‘Epworth NE’. Don’t worry – it’s not a problem and it has been processed correctly.

3. The map’s code is contained within the URL. In the example case, the URL is: The part in bold is the bit you need to copy – it’s between ‘snapshots/’ and the hash (#) symbol.

Interested in where you field paper lies in Epworth?

You can see the grids for each of the quadrants here, in the Field Papers website:


North-West (Note it says NE on the Field Papers website, but this link is correct)



Load the layers into JOSM

1. In JOSM, click on Field Papers\Scanned map

Field Papers Menu Bar.JPG

and copy the code into the box and click OK:

Field Papers URL Entry.JPG

You should get something looking like this:

Field Paper in JOSM.JPG

2. Now download the relevant imagery (usually Bing) using the imagery tab at the top of JOSM:

Epworth Bing 1.JPG

(Note: sorry about the red text over the area - this shouldn't happen for you. If it does, try zooming in and out and see if it disappears)

And the OSM data using the ‘download’ button:

JOSM-Icon Daten download.jpg
Epworth Bing OSM 1.JPG

3. Next, ensure ‘Bing aerial imagery’ is selected in the layers menu, and reduce its opacity using the button on the right-hand side of JOSM just under the layers menu. Use the bar to set the opacity so you can easily see the OSM data, the scanned map and the Bing imagery. An example is below, but you may find a different amount of opacity easier for you. The Opacity button is the one which is a vertical bar changing from black at the top to white at the bottom.

Layers box with Field Papers.JPG
Bing OSM Field Papers in JOSM.JPG

4. Start mapping!

Start Mapping

Tagging in Epworth

The nature of addresses in Epworth means that the tags we use are rather different from those that you would use normally.

The tags you will need are:

  • source
  • addr:ward
  • addr:hamlet
  • addr:neighbourhood
  • name
  • loc_name
  • building
  • building:material

You may not need to use all of them - there may be information missing. Equally, if there are other tags that aren't included here but you think are relevant, please add them too.


Please enter the key source with the value survey. This allows us to identify what information has come from the field papers and surveys.


When Epworth was founded in 1890 it was split into seven wards, and this system still exists in Epworth. They are administrative designations and do not always follow the same boundaries as the other area types!

The tag for wards is addr:ward and the value is the ward number written as a number - e.g. '2' rather than 'Two' - this goes for all numbers in the surveys.


Hamlets are the largest region within Epworth (excluding wards, for the reasons explained above). There are currently 15 hamlets which have been identified within Epworth:

  • Chinamano
  • Chinamano Extension
  • Domboramwari
  • Glenwood
  • Glenwood Park
  • Jacha
  • Makomo
  • Makomo Extension
  • Muguta
  • Muguta Extension
  • Nyikavanhu
  • Overspill
  • Pamajuta
  • Pentagon
  • Zinyengere

The tag you want to use for these is addr:hamlet and the value is the name of the hamlet (each word in the name starting with a capital letter, as above).

All other names of areas are treated as neighbourhoods, as shown below...


Neighbourhoods are areas within hamlets. There are many of them noted in the field papers. They are names which have sprung up as the neighbourhoods emerged, and as such there are some quite interesting ones!

The tag for neighbourhoods is addr:neighbourhood and the value is the name of the hamlet (each word in the name starting with a capital letter).

Note that neighbourhood has the British spelling rather than the American spelling.


As mentioned previously, this is the unique identification of the plot within Epworth. Note that there may be more than one building on a plot.

The tag for this is name rather than number. The value of the tag is the number of the plot (e.g. 8413)

Local name

Sometimes, more information about the plot is available, for example:

  • Often, this is the name of someone who lives there. Anyone whose names are in the field papers have consented to their names being in OpenStreetMap and so it is fine to put these into the map.
  • If the building/plot is a shop and has a name, put the name of the shop as its local name and its address number as the name.

The local name is inputted into OpenStreepMap using the tag loc_name.

Building use

The surveys often include what the building is used for. If the buildings are already mapped (they should be), they are likely to have the tag building = yes. If you have information about the use of this building, please update this tag. Examples of values are:

  • residential for housing
  • retail for shops

Building Material

Many of the surveys mention what the buildings are made of. There is often more detail on the survey paper than necessary - 'field brick', 'concrete brick' etc should be entered simply as 'brick'.

The key is building:material and the value should be the most suitable on from the list in Key:building:material. (Note: CB in the surveys means 'concrete brick' so it should be entered as brick.)


For this, I’ll use the SE E5 tile as an example, but you can use a different tile. Mine looks something like this:

SE E5 Field Paper Epworth.JPG

The survey looks like this:

SE E5 Epworth Survey.JPG

Immediately, a few things pop out at us.

Firstly, there’s loads of names of people! This is quite uncommon, but not something we can’t deal with - they go in under the loc_name tag. They’ve used the Neighbourhood column because there’s nowhere else to put the information. This means that the neighbourhood information has been shifted into the area column. This isn’t a massive deal - you just have to work out what the surveyor was trying to get across!

Secondly, the ‘area’ these buildings are in seems to be called ‘Chinamano Origin’ or ‘Chinamano Original’. Although this isn’t one of our hamlets, Chinamano is. So here’ we can assume that ‘Chinamano Origin’ is a neighbourhood within the hamlet of Chinamano since the names are so similar. And we should put them all as ‘Chinamano Origin’ rather than ‘Chinamano Original’ because although we don’t know which is correct, there’s only one ‘Original’ and eight ‘Origin’ names on the survey.

Next, we see that most of the buildings have numbers, but not all of them do. That’s okay because the building without a number is a school building. They all have construction materials recorded and are in Ward 4.

The ID# does not need to be recorded in JOSM - it is simply an ID used to match up the buildings on the hand-drawn map with those in the survey paper. They have no other meaning.

So now we know what the main tags will be:

  • source=survey
  • building=residential (except for B2)
  • building:material=brick (except for B9)
  • addr:ward=4
  • addr:neighbourhood=Chinamano Origin
  • addr:hamlet=Chinamano
  • name= a number (except in the case of B2)
  • loc_name= someone’s name (except for B2)

Now we have to put the information into JOSM. It's generally easier to work from the top downwards.

Add the tags into JOSM

Return to JOSM, with the field paper overlaid, to find B1:

Epworth Tutorial B1 1.JPG

Now we have to create a node in which to put the information. The addresses belong to plots of land rather than buildings, so there are several potential situations:

  1. There are no buildings on the plot. If this is the case, the node should be placed near the centre of the plot.
  2. There is one building on the plot. Place the node in the building, but not attached to it. Please create new nodes within, but not attached to, the building you are tagging. This is the standard we are using at the moment.
  3. There are multiple buildings on the plot. Try and put the node in/near the largest building, or in the middle of any cluster of buildings on that plot.

Back with our example, it appears that the building highlighted is the relevant one - it’s quite large and is right by the B1 marker. To create a node, click the draw nodes’ button like this in the top-left of JOSM, or press the A key on your keyboard. Your cursor should now turn to a crosshair.


Double click to add a node where the cursor crosshair is. You don’t want the building in which you’re placing the node to be highlighted when you do this. If you can’t manage to un-highlight the building, zoom in two or three steps and try again. Go back to select mode by pressing S or the select button in the top-left of JOSM.

Objekte auswaehlen.png

The node should look something like a small red square:

Epworth Tutorial B1 2.JPG

It’s red rather than yellow because it’s automatically selected for editing. If you change to select mode, you can deselect the node and it will turn yellow. To select it again, ensure you’re in select mode and single click on the node.

You can move the node when you’re in select mode and have it selected by dragging it across the screen.

Now we need to add the tags to the node. To do this, ensure that your Tags/Memberships section is open. It is on the right hand side under layers and above Selection.

Epworth Tutorial JOSM RHS.JPG

With the node selected, click the ‘+ Add’ button

Add Tag.JPG

and a box will appear, looking something like this:

Add Node Fields.JPG

This is where we add tags. The top field is for the tag type, and the bottom one is for the value of that tag. If you look at the drop-down menu you will see dozens of tag types:

Add Node List.JPG

You can also just start typing one, and it may autofill the correct word:

Add Node Autofill JOSM.JPG

To select that tag type, either press Tab or click in the bottom box. Then, add the necessary value. In this case, it’s 1598:

Add Node 1598.JPG

Click OK or hit Enter to confirm the new information. You will see it pop up in the Tags/Memberships section on the right hand side:

Tagged 1598.JPG

Depending on what type of tag it is, it may have modified the node’s appearance too. In this case, the name appears next to the node:

1858 in Epworth.JPG

Next we add the other values. building=residential also affects its appearance:

House 1858 in Epworth.JPG

Eventually, the list of tags should looks something like this:

1858 all tags.JPG

Well done! You’ve tagged your first building.

When you do your subsequent nodes, it is often easier to copy a node than to start from scratch again. For example, we can copy our recently-created node by selecting it, pressing Ctrl-C (Command-C on a Mac?), placing our cursor where we want to build the new node, and pressing Ctrl-V (Command-V) to create it:

Cloned 1858.JPG

It has all the same attributes as the original node except for its location. So you’ll need to change some of the tags to update it to the relevant information. I’ve dragged the node to the correct place, in this case in the building B2:

Cloned B1 in B2.JPG
B1 B2 in Epworth survey.JPG

It’s still in Chinamano Origin (and therefore Chinamano too), and also still in Ward 4. It’s made of bricks too, so none of these tags needs to change. We will need to change the name, the building type and remove the loc_name tag.

To remove a tag, highlight it in the list of tags and click the delete button

Add Edit Delete.JPG

To edit a tag, highlight it in the list and click the ‘edit’ button (no surprises there). The dialog box reappears, and you can now change whatever you need to, and then click OK to confirm the change.

Here, I’ve changed the name to ‘School Staff House’. This could arguably go as a loc_name but I’ve put it in as a name as this is likely to be the primary identifier of the building. If it had a number like the local houses, the number would go under name and School Staff House under loc_name.

Keep doing this with all the lines in your survey until you’ve finished it!

Alternative Survey/Map

Sometimes the survey information is written directly onto the map:

NW C6 map survey.jpg

There isn't a separate survey sheet for these - pleae just try your best to interpret the information on the map.

If you have more survey paper records than are recorded on the field paper, or vice versa, please mention this when recording what you've accomplished (the section coming up).

Upload and record progress


Now you need to upload your work to the server. Press the upload button in the top left of JOSM. Please use the tag '#MissingMaps #EpworthSurveys'

JOSM DatenUploadIcon.png

You may get some validation errors - please fix these if you can! They will be detailed in the Validation box in the bottom right of JOSM:

JOSM Validation Box.JPG

Once those are dealt with, this screen should appear, with all of your work summarised:

JOSM Upload Box.JPG

This shows only one node being uploaded, but yours should show as many as you’ve created. Please write #MissingMaps #EpworthSurveys in the comment box, and write Survey in the data source. If you’ve used Bing imagery for anything, include that as well, separating them with a semicolon and a space, i.e. Survey; Bing

Press Upload Changes to upload your changes. If you’re not logged in, you may be asked to enter your OSM login details first.


Upload your changes to the Tile completion record by changing the colour of the cell corresponding to the tile you've just worked on to yellow if you didn't finish it, or green if you did. Please don't leave it as pink - it'll stop others working on it!

If you've got extra plots on your field papers than your surveys or vice versa, mention this in the comment on the Tile completion record on the square relevant for your tile.

This is the end of the tutorial