7. Introduction to Mapping with JOSM#
7.1. Overview#
Welcome to Course 7 of the Youthmappers Academy. In this module, we will take a look at JOSM, or, the Java OpenStreetMap Editor. JOSM is a desktop editing application for OpenStreetMap, written in Javascript, which provides a whole host of advanced editing tools for working with OSM data. JOSM is also the preferred tool for validation in OSM (we’ll talk a little more about validation in the next module). Apart from the advanced editing functionality of JOSM, one of its primary benefits is that it allows you to download and work on OSM data offline, which is incredibly beneficial in low/no bandwidth areas.
7.2. What is JOSM?#
7.2.1. Overview#
Java OpenStreetMap Editor (JOSM) is an advanced desktop editing application for OpenStreetMap, written in Javascript. It runs on Windows, Mac OS, and Linux operating systems, so is widely accessible. Mappers “check-out” or “download” OSM data to edit offline (which is a huge advantage in low bandwidth areas). When editing is complete, mappers “push” or “upload” their data back to the OSM server. There are built-in checks as part of the re-upload process to check for correct geometry and complete tagging. While JOSM supports the editing and re-upload of existing nodes, ways, tags, and relations that have been downloaded from the OSM database, it also supports the editing of stand-alone GPX tracks and GPX track data, before this data is added to OSM.
New mappers may find the JOSM interface slightly intimidating, but with practice, most mappers find JOSM to have a much more efficient editing workflow than iD editor, with many great shortcuts to expedite the mapping process.
7.3. JOSM Installation#
7.3.1. Overview#
If you don’t already have a copy of JOSM on your machine, you will need to visit the following link and install the version of JOSM for your operating system: JOSM Installation Files.
There are two main categories of installation available to the user:
The josm.jnpl option, also known as the “web start” option, allows users to start the application software directly from the internet using a web browser. The main benefit of this option is seamless version updating and greater control of memory allocation.
The josm-tested.jar version is the standard desktop installation (which works across all operating systems), but you can also click on the dedicated install links for certain popular OS (windows/macOS) from the front page.
7.3.1.1. So Which One Should I Choose?#
Every regular JOSM user has a preference for one installation or another. I’ve tried both (.jnpl and dedicated OS install), and both have worked equally well for me. More recently I’ve opted for the .jnpl install, as the automatic updates are a really nice feature. For someone who uses JOSM regularly, it really does cut down on maintenance.
It is important to note that JOSM requires the most recent version of Java to be installed on your machine in order to function properly. You can either go to Java Installation to check and see that you have the latest version of Java installed, or, wait for the prompt during the JOSM installation, which will also alert you to update your Java (if necessary).
7.5. Tour the Interface#
7.5.1. Map View#
Before we download or edit any live data, let’s tour the JOSM interface and practice drawing some simple features.
Go to File > New Layer. You will see the following screen: 7.08
MacOS View:
PC View:
The main window or panel within the interface (the part which is currently black) is called the Map View. This is where the data is displayed and where the editing takes place.
Surrounding the Map View panel, you will see various toolbars and menus. These toolbars and menus are customizable depending on which plugins you have installed. Therefore, your view may differ slightly from the screenshots.
7.5.2. Toolbars#
These are the main drawing tools:
Select (S) (top)
Draw Nodes (A) (bottom)

These are the tools to open, save, download, and upload your data:

These are the preset tagging tools, for popular road/street, transport, and facility tags:
7.5.3. Information Panels#
The Information Panels to the right of the Map Frame show information about the data in JOSM, the different layers in the view, the imagery being used, how objects are tagged, and who the last mapper to edit a feature was.

You can customize which panels you’d like to feature in this bar on the right-hand side of the map view. The options are available under the “Windows” drop-down menu at the top of the screen.

Note: The options you see in your Windows drop-down list will depend on the plug-ins that you have installed on your machine.
7.5.4. Status Bar#
Finally, at the bottom of the JOSM window, the Status Bar gives coordinates and measurements for features, as well as a hint of the current tools.
7.6. Drawing Features in JOSM#
7.6.1. JOSM: Drawing Basic Features#
7.6.1.1. Overview#
Remember, we first covered OSM data types in Course 2 when we learned how to draw our first features with iD editor, and also in Course 4, when we learned about the OSM data model.
Here is a quick reminder:
7.6.1.2. JOSM Basic Editing Tools#
Select: For selecting elements, viewing/editing their tags, and moving them (Keyboard shortcut: S for PC and MacOS). Just click on the “Select” tool and use the left mouse button to select and/or move your object.
Draw: For adding elements such as standalone nodes, adding new nodes to create a new way, or extending an existing way (Keyboard shortcut: A for PC and MacOS).
Delete: Delete is for deleting elements. You simply select a feature (using the select tool) and then use the delete button on your keyboard (PC) or Fn+delete (MacOS). Alternatively, you can enter into Delete Mode which will delete every feature you left-click on with your mouse. You can enter into Delete mode by:
Shortcut Key (Keyboard shortcut: Ctrl+Delete (PC), Fn+delete (MacOS)
Mode Menu (Which will add an icon to your edit toolbar).
Once you’ve activated Delete Mode, click on nodes, way segments, and ways to delete them.
7.6.1.4. Drawing a Node#
To draw a standalone node:
Click on the Draw/Add tool (keyboard shortcut: A). When you move your mouse over the Map View, you will see a little crosshairs icon.
Double-click quickly on the left mouse button to create a single node. Note: If you don’t double-click quickly enough, your draw tool may stay activated, and attempt to draw a line. If this happens, hit escape on your keyboard, and your drawing will revert to a single node.
7.6.1.5. Drawing a Way#
To draw a way:
Click on the Draw/Add tool (keyboard shortcut: A).
Click once on the map canvas to draw the first node of your way.
Click again on the map canvas and another node will appear, joined by the first segment of a way.
Keep clicking to continue to draw a way with several nodes and segments on it.
To finish the way, either double click, click on the Select tool (keyboard shortcut: S), or hit the Escape button on your keyboard.
7.6.1.6. Drawing an Area#
Drawing an area in JOSM is much the same as drawing a way⏤the only difference is that you have to close or complete the area by deliberately returning to the first node you drew and double-clicking. This is essentially “closing” the way.
Once again, click on the Draw/Add tool (keyboard shortcut: A).
Click once on the map canvas to draw the first node of your area.
Keep clicking to continue to draw an area with several additional nodes.
When you have defined the shape of your area, double-click once more on the starting node to complete it. Note: You might have to check to make sure that you are “snapping” to the right node before you commit to your last double-click.
7.6.1.7. Tagging#
We learned about tagging in both courses 2 and 4, but as a quick refresher:
In order to tag something in JOSM, you must first select the feature you want to tag.
As a rule of thumb, if a feature is grayed out, then it is not selected. If it is highlighted in red, then it is actively selected and ready for re-editing (and/or tagging).
Click the Select tool
Using the left mouse button, select the feature you wish to tag
Go to the Tagging menu in the Information Panel, and click Add
In this instance, I want to tag the selected area as a simple building. So, in the Key drop-down menu, I select “building”. Note: You can either scroll to this alphabetically or start to type it and the menu will navigate to it.
In the Value drop-down menu, choose Yes
Click OK
You will notice that the new building now has a light pink fill. The building tag has already helped to define the symbology for this feature.
If you wish to tag several features with the same tag simultaneously, you can select multiple features using the Select tool, then using the Add button from the Tagging panel.
Another nice feature of the JOSM tagging tool is that it remembers the last tagging pair used. You will notice in the last .gif that the tagging pair of building + yes was already populated. In fact, the tagging feature recalls the last five tagging pairs used. This is particularly handy when you are working with several recurring map features within a given area.
Add Tag Dialog Box: PC and MacOSM View
You will have to develop a certain familiarity with the OSM data model in order to get comfortable with and make full use of the tagging system within JOSM. It would be a good idea to revisit the Map Features page on the OSM Wiki to get a refresher on some of the most commonly used tags. This is an incredibly detailed resource, and there is always something new to learn.
Click here to navigate to the Map Features OSM main page.
7.6.2. Shortcuts in JOSM#
One of my favorite aspects of working in JOSM is the many keyboard shortcuts you can use to streamline your mapping workflow. Instead of having to locate a specific tool from a toolbar (or buried several levels deep in an editing menu), you can activate that same tool using a single keyboard shortcut. This may not seem like a timesaver right now (especially when you will have to learn what shortcut goes with what tool), but when you become familiar with them you will see a noticeable difference in the speed and efficiency with which you map!
Once again, these shortcuts might vary depending on your operating system, but they are mostly consistent. See here: https://josm.openstreetmap.de/wiki/Shortcuts
There is also this handy visual, one that I have printed out and have hanging over my desk!
Image Source: JOSM Keyboard Shortcuts, Wikimedia Commons
7.7. Working with Real OSM Data in JOSM#
7.7.1. Adding and Downloading OSM Data#
7.7.1.1. Overview#
One of the main benefits of working with JOSM is that you create and update data offline, so data usage is limited. This is particularly handy when working with low or inconsistent bandwidth. There are several different ways to download data locally to JOSM.
To explore these, go to File > Download data or click on the Download data button (green downward arrow)

In the Download from OSM dialog box, you will see five tabs that indicate the five different ways you can download data for editing
Different ways you can download data for editing:
Slippy Map: Using your mouse, or the +/- buttons on your keyboard, pan and zoom around the map to find the area you would like to edit. When you’ve identified it, simply draw a box around the extent you wish to download and click on the Download button.
Bookmarks: In this tab, you can save the coordinates of geographic extents that you visit/edit on a regular basis. This is particularly useful if you are working on a recurring project, or, you like to keep an eye on the changes in your local neighborhood.
Bounding Box: If you know the bounding coordinates of the area that you would like to download, then you can either enter them here manually, or (and this is how most mappers use this tab) you can visit www.openstreetmap.org, search for the area you wish to map, copy/paste the URL into the text box in the Bounding Box tab, and click on the Download button.
Areas Around Places: In this tab, you can do a regular word search of OSM to find place names or features that are near a particular place.
Tile Numbers: In this tab, you can specify a specific tile address to locate and download.
My favorite way to locate the area I wish to map is to find it on www.openstreetmap.org, copy the url, and then use the Bounding Box tab to jump immediately to that area. Take a look here:
What I also like about this option is that you can check the area you wish to download BEFORE you click on that Download button, by hopping back to the Slippy Map tab after you’ve pasted the URL from www.openstreetmap.com.
The editing interface and the appearance of the downloaded OSM data are quite different to what we are used to in iD editor.
Click on any of the existing features to see how the attributes are displayed in the Tags/Memberships window:
Notice that the bounding box that you specified in the Download dialog is indicated by a clear black background. JOSM downloads all data that intersects with the bounding box that you specify, hence the additional data trailing beyond this bounding box.
If your bounding box is set by a tasking service such as the HOT Tasking Manager, or the TeachOSM Tasking Manager, you should only edit the data that falls within the black box, and refrain from editing any features that fall within the striped/crosshatched area, as those features fall within the task area of another mapper.
7.7.1.2. Adding Imagery to the Editing Window#
Unless you are working with a Tasking Manager, such as the HOT Tasking Manager, or the TeachOSM Tasking Manager, imagery does not automatically appear behind your downloaded data.
To add imagery to the window, go to the Imagery drop-down menu at the top of the screen. Notice you have many of the same imagery options that you are familiar with in iD.
I’m choosing Bing imagery for my editing session as I have edited in this area before and I know that it has the best resolution and is the most current.
You can add several different imagery sources to your JOSM editing session, and you can switch between them quickly and easily to assist your editing decisions. You can turn the imagery layer on and off and also adjust the opacity, contrast, and sharpness of the image.
7.7.1.3. Managing and Deleting Data Layers in JOSM#
If your initial data download was for a particularly busy or previously well-mapped area, then you may want to consider removing that layer and re-downloading a smaller, more manageable area to map.
To delete the first layer that you created, click on the little waste bin icon in the bottom right-hand corner of the layers window, or simply turn it off by clicking on the little eye icon beside the layer name.
You can then add an additional data layer to the map window by downloading a new geographic extent.
If you have not made any changes to a layer that you have downloaded, deleting it simply removes the downloaded layer from your device⏤it doesn’t delete it from OSM (remember, it’s just a localized copy). If you have made any changes to the layer since you’ve downloaded it, JOSM will always give you a warning to check if you really wish to delete the layer or to review and upload your edits.
7.7.2. Editing and Uploading OSM Data#
7.7.2.1. Overview#
Now that you’ve downloaded some real OSM data, let’s revisit the editing process in JOSM and walk through the process of saving and re-uploading to OSM.
This is a download of a much simpler area, one that has new development (and recently updated imagery). I’m going to trace several new houses and upload them to OSM. Simply follow along for now. Then, you can replicate the steps in an area of your own choosing.
Note that it is important to check several imagery sources before you begin mapping, both to identify the most current imagery and for any potential offset issues.
These side by side images show the same area (with main road highlighted for reference), and you will see that the new construction is missing from the image on the left (Bing imagery).
7.7.2.2. Drawing a Building#
Remember, to add a new feature, click on the Draw/Add tool (you will see a little crosshairs icon as you move over the map window)
Click once on the map canvas to draw the first node of your building
Keep clicking to continue to draw your building, using several additional nodes (depending on the shape of the structure)
When you have defined the shape of your building, double-click once more on the starting node to complete it. (Again, you might have to check to make sure that you are “snapping” to the right node before you commit to your last double-click.)
To square your building, make sure that the building is still highlighted, then click the “Q” key on your keyboard. (“Q” stands for orthogonalize, which is a little obscure, but remember the shortcut “S” has already been taken for “Select”.)
To tag your building, click on the Edit button in the Tags/Membership window, and select “Building” and “Yes”
7.7.2.3. Saving and Uploading Data to OSM#
If you have a reliable connection, it’s good practice to save regularly. (Remember, this was a practice we spoke about when mapping with iD editor. It’s the best way to prevent conflicts if there are other active mappers in your area.)
Go to File > Upload Data or simply click on the Upload Data button (green up arrow)
You will see the following interface:
Add a changeset comment (remember this from iD, it’s a brief description of the work that you have completed in this editing session)
When you are happy with your changeset comment, click Upload Changes
If there aren’t any errors with your drawings or tags, then your data will upload successfully and you will receive verification from JOSM
Tip
YouthMappers Blogspot: Tech Tips for Better Mapping
Tech Tips for Better Mapping By Leigh Seitz, College of William & Mary (USA)
Hear from Leigh as she shares her experiences in switching from iD Editor to JOSM during her time as an intern at the USAID Geocenter.
7.7.3. Dealing with Errors During Upload#
7.7.3.1. Overview#
We will look at the Validation workflow in more detail in the next course, but every new mapper has to learn to deal with errors and fixes to the data they create in order to successfully upload their edits to OSM.
In the image above you can see an attempt to upload two (deliberately incorrect) buildings to OSM. JOSM picks up on the incorrect geometry, the fact that the buildings are overlapping, and that one or more of their nodes are connected or “glued”.
Once the JOSM uploader detects the errors, it automatically adds the “Validation Results” window to the right-hand panel. Using this panel, you can navigate/zoom directly to the offending geometry to fix it, which is particularly useful when you have a lot of data. We will look at this panel in more detail in the next course.
7.7.3.2. Fixing Overlapping Buildings#
In the previous example, we had two overlapping buildings rejected for upload. Let’s fix them quickly, and push the corrected geometries to OSM. Again, this is an illustrative example, just follow along.
First, zoom in on the features you wish to fix so that you can clearly see the error and any nodes that need to be selected and moved.
Select your nodes one by one, and place them in the correct position.
Depending on the drawing tool/method used, you may encounter nodes that are joined or “glued” together and when you attempt to reposition them, the walls of both buildings start to move with you.
Select the joined/glued node.
Go to Tools > Unglue Ways (keyboard shortcut: G).
You will see that the two nodes are now separated. You can move them independently of one another to more appropriate locations.
Always make sure to select and square and buildings that you have edited (using the “Q” button on your keyboard).
You will notice that there are many different geometry editing options available under the Tools menu. We won’t go through each of the options one by one, but you should explore these on your own time to become familiar with their function. You will probably recognize quite a few from your time editing in iD editor.
When you are happy with your building edits, you can attempt to re-upload the data to OSM. This time, you should have no issues with the upload process.
7.8. Dig Deeper#
7.8.1. Want to Dig a Little Deeper?#
LearnOSM: Getting Started with JOSM
LearnOSM is an online resource with step-by-step instructions (in multiple languages) on the many tools and platforms that can be used to generate or add data to OpenStreetMap. It features a section on iDEditor, JOSM, and editing using smartphones.
OSM Wiki: JOSM Homepage
This includes detailed installation instructions and a user guide.
OSM Wiki: JOSM Shortcuts Cheat Sheet
This is an excellent visual to help you remember the many keyboard shortcuts to expedite your editing in JOSM.
There are also many excellent video resources on YouTube about how to map in OSM, created by the growing OSM community. Here are some of our favorites:
HOT Channel: How to Map Buildings in JOSM
HOT Community Webinar Recording: Introduction to JOSM
7.9. Assignment#
7.9.1. JOSM 1: Introduction to Mapping With JOSM Assignment#
For the following assignment, you will demonstrate your ability to use basic mapping functions in JOSM. You will be asked to add tagged buildings, roads, and points of interest to the .osm file provided. You will not upload this data to OSM. You will resave the edits you have made and submit the file to the YouthMappers team for review and grading.
7.9.2. Instructions#
Download the following file: JOSM_YM_Demo.osm
Launch JOSM, and open the file
Go to the Imagery drop-down, and turn on the Bing imagery source (there is one building contained in this demo file, and it is sufficient to navigate you to the correct location on the imagery)
Trace and tag the following features: a. Four simple buildings (tagged with building = yes) b. Three examples of Road tracing (tagged with suitable highway tags, such as secondary, tertiary, or residential) c. Three additional features with detailed tagging (see the screenshot below to locate these features). Please apply the following tags: i. School
Amenity = School
Name: Red School ii. Shop
Name: Red Shop
Opening Hours = 7-11
Wheelchair accessible = yes iii. Soccer Field
Leisure = Soccer pitch (or pitch)
Sport = Soccer
Name: Green Fields
Surface = Artificial Turf
Save your edits to the data layer (using the following format “JOSM_YM_yourname”).
Remember: Do NOT upload the contents of your edited file to OSM. This file is for demonstration and grading purposes only.
Not everyone’s attempt for this assignment will look exactly the same, but your submission should look close to the example below. REMEMBER:
Buildings should be squared
ALL features should be tagged (even if it’s just building = yes)
Road features should NOT be angular and messy, but should honorably follow the centerline of the road on the imagery provided
Example of a fully edited submission with imagery Note: The field, school, and shop should be the same, the roads and basic buildings can be of your own choosing.
Example of a fully edited submission without imagery Note: The field, school, and shop should be the same, the roads and basic buildings can be of your own choosing.
To save the edits to your layer file, right-click on the layer in the Layer menu and select Save As. Save your changes to a file with the following naming convention: JOSM_YM_”your name”.osm (e.g: JOSM_YM_JaneSmyth.osm)
Tip: Save your version of the file after you make your very first edit. Continue to right-click and save regularly while editing.
7.10. Conclusion#
7.10.1. Skills, Proficiencies, and Standards#
Each badge awarded as part of the YouthMappers Academy has been aligned to the skills and proficiencies outlined in the U.S. Department of Labor’s Geospatial Technology Competency Model (GTCM), as well as National Geographic’s National Geography Standards.
The Geospatial Technology Competency Model identifies the foundational, industry-wide, and industry sector-specific expertise that distinguishes, and binds together, successful geospatial professionals. It identifies core personal, academic, and workplace competencies, as well as sector-specific geospatial knowledge and abilities, including specialized competencies related to data acquisition, data analysis and modeling, imagery interpretation, and software and application development.
The National Geography Standards are benchmarks of geographic literacy to determine a comprehensive understanding of the interaction of space and place, and the skills to analyze and critique these dynamics. These standards are measured through knowledge and mastery of three things: (1) factual knowledge; (2) mental maps and tools; (3) and ways of thinking.
The Geospatial Technology Competency Model
Interpersonal Skills: Demonstrating the ability to work effectively with others, through interaction with peers and course moderators
Professionalism: a. Demonstrating commitment to the values, standards of conduct, and well-being of one’s profession b. Know codes of ethics and rules of conduct; legal, ethical, and business aspects of data sharing
Initiative: Demonstrating gumption at work/school
Dependability and Reliability: Displaying responsible behaviors at work/school
Lifelong Learning: Displaying a willingness to learn and apply new knowledge and skills
Reading: Understanding written sentences and paragraphs in work-related documents
Geography: Understanding the science of place and space; geographic skills
Science and Engineering: Knowing and applying the principles, rules, and methods of science and engineering to solve problems; subject-specific scientific knowledge
Basic Computer Skills: Using a computer and related applications to input and retrieve information; navigation and file management and internet and e-mail
Planning and Organizing: Planning and prioritizing work to manage time effectively and accomplish assigned tasks; planning and organizing; adaptability and flexibility; time management
Data Quality: Accuracy, resolution, precision, fitness for use; quality control versus quality assurance; data quality implications of legacy systems
Geographic Information Systems: Conceptual foundations, including representation and uncertainty; digitize and georeference paper map or plate; acquire and integrate various data types in GIS database
Software and Application Development: Evaluate open source software
Working with Tools and Technology: Selecting, using, and maintaining tools and technology to facilitate work activity
The National Geography Standards:
The World in Spatial Terms: a. How to use maps and other geographic representations, geospatial technologies, and spatial thinking to understand and communicate information b. How to analyze the spatial organization of people, places, and environments on Earth’s surface
Places and Regions: The physical and human characteristics of places
Environment and Society: a. How human actions modify the physical environment; b. How physical systems affect human systems
The Uses of Geography: a. How to apply geography to interpret the past b. How to apply geography to interpret the present and plan for the future
Knowledge Checks
To test your knowledge, complete the following test:
If you receive a score of 80% or higher, you will receive an email with a certificate for this module.