↑ OpenStreetmap Hacker's guide ↑↑ Net & Web  

Contributing to OpenStreetmap

Other docs -- Map features -- JOSM

Existing documentation

This is a topic on which there is much more documentation than about other topics, presumably because it involves a transfer of information to rather than from OSM.

A website not directly affiliated with OpenStreetmap, LearnOSM, offers basic to intermediate instructions and is available in a large number of languages. There is a github repository for LearnOSM content that allows cloning all its content in one go. The github site also contains links to further docs, but they are controlled by Google Docs and download protected by HTTPS and JavaScript.

The OpenStreetmap wiki also contains more information on contributing than on any other topic. There is an introduction to contributing, for example, and many pages on special topics that will be referenced in the following.

How to describe new geography — following conventions

The important thing when building a collaborative data base like OpenStreetmap is that different contributors attach the same meaning to the same metadata. Otherwise map feature with the same appearance will mean different things in different places. Properties of map features and objects are decribed by "tags", key-value pairs which can have specific conventional values.

The central wiki page to consult is the very long page about map features. It lists (almost) everything that can be included in the database and links to many specialised pages that describe more specific attributes for most features. Read relevant parts of the overview page and specific dedicated pages before each edit! Your memory is not as good as you remember it to be, and conventions sometimes change.

Common-sense advice on tagging:

Using JOSM

Basics -- Editing paths -- GPS imports

There are two different generations of web interfaces for editing the OpenStreetmap database, but for serious contributors, JOSM is the way to go: With it you can import track data, save and load unfinished work locally.

The features of JOSM are well documented both in a wiki of its own and in pages on the OpenStreetmap wiki. If I understand correctly, it is still under development, and some menu items do not work yet, but it is certainly quite useful and efficient to work with. A minor quibble is that its Java GUI does not play well with X11 window managers, with windows losing focus for no reason, but still accepting input.

JOSM basics

A basic JOSM editing session goes as follows:

Downloading current map data
The download button or the File → Download from OSM menu item allows you to specify the region you want to edit in quite many ways. Probably the easiest is to use a web browser to display the right area and paste the URL into the text area in the Bounding Box tab.
The map display
After retrieving the data, JOSM displays the map features on a black background, with the area outside the designated region hashed out. Don't edit outside the region, as not all map features there have been downloaded (though some that also intersect the region of interest may extend outside it). You zoom the map with the mouse scroll wheel or the + and - keys, and move the map by grabbing it with the right mouse button.
Creating new map features
Every map feature is either a node (=point, e.g. a mailbox, phone booth, ...), a path (road, river, ...) or closed path (house outline, administrative area, ...). You use the third icon on the left to create new ones (the icon shows a single path segment). The first click creates a node, more clicks create a path, as indicated by the rubber line from the previous node. New nodes snap to existing ones, to close a path or branch off from an existing one, unless you hold the Control key. To start a new path, hold the Shift key.
Moving and extending existing features
This is done with the first icon on the left (hand on a path). You select a node or a path with a single left-button click. Before clicking, you can see what you are doing because the focused node or path is outlined in red. You move a node or whole path by dragging it. All path segments have little crosses in the middle (unless you are zoomed out too much). These are for inserting additional nodes — just drag them.
Modifying metadata
Once you have selected a path or node, its metadata will be displayed in the right part of the JOSM window (if not, enable Windows → Tags/Memberships). You can edit the existing entries or add new ones with the buttons in that sub-window. This is not difficult technically but can be mentally. Remember that OpenStreetmap is a database that can be used for more than one purpose. What infomation might someone conceivably want to search for? Is this just a generic building, can't you tell if it is residential or industrial? Have you marked sub-features, such as a node in the outline of a bank where there is an ATM? Don't use the note tag unless there is really no standard tag expressing the same information. Search the map feature page linked above and plausible specialised feature pages linked from it.
Saving your changes locally
The region being edited can be saved to a local file with the menu item File → Save As.... This allows you to still get some sleep tonight and finish your edit later. The file format is the standard OpenStreetmap XML format. Nodes and paths newly created by your edit have negative IDs. Both new and modified nodes or paths have the additional attribute action='modify'. Deleted nodes and paths still exist in the file but are marked with the attribute action='delete'.
Uploading your changes
You use the upload button or the File → Upload Data menu item to send all your changes to the OpenStreetmap server. You have to enter your account details. There is also a menu entry to upload only selected objects (but I have not tried it).

Tips for editing paths

JOSM provides several functions to make working with paths (ways) easier. They are located in the Tools menu. Here are some of their applications:

Houses with rectangular outlines
Draw the approximate outline, then click Orthogonalize Shape to correct the right angles.
Houses with regular polygonal outlines (yes, they exist)
Create a closed path with the right number of nodes and of the right size, then click Align Nodes in Circle.
Branching off from an existing path
This is needed for creating a new side road or a tributary to a river. If there is a node on the existing path where the new path should be attached, just let the last node of the new path snap to the existing node, and perhaps adjust its position slightly. To create a new node at the branch-off, use Move Node onto Way after selecting the node and the path. (Shift-left-click allows you to select multiple objects in selection mode.) (If the segment it is subdividing is large enough to have the + in the middle, you can also just snap the node to it.) If this happens by mistake, you can undo it with Disconnect Node from Way. If you want to make an existing path branch off another, you can move its end node while holding Ctrl to make it snap to other nodes.
Attaching different metadata to different parts of a path
To do this you have to split the path into two (or more) paths with Split Way after selecting the node where you want to cut. Each part will inherit the metadata of the old combined path, but you can now edit them independently. An example of this is when you have discovered that a road represented by a single path is partly tarmac and partly gravel.
Pruning nodes from paths
Roads or other paths that are mostly straight may have more nodes than needed. Simplify Way removes nodes that contribute little to a path's location and thereby prevents bloat in the OpenStreetmap database. Its default setting is too imprecise for my liking, so I have set its accuracy to 1 meter. You change this setting in the preferences dialog (Edit → Preferences), by enabling expert mode, in Advanced Preferences (wrench icon at the bottom), entry simplify-way.max-error.
Path direction
In most cases, the direction of a path does not matter. When joining paths, they have to have the same orientation, but you are prompted to fix that when necessary. However, rivers by convention have a direction reflecting their flow direction. You can reverse the direction with Reverse Ways.

Importing GPS tracks

The easiest and most accurate way to survey new roads and other paths is by travelling on the road and recording a GPS track. JOSM somewhat supports this workflow. I will first describe JOSM usage and then the necessary preprocessing.

JOSM allows to open multiple OpenStreetmap XML files with File → Open which become several layers. A sub-window on the right shows all layers (enable or disable with Windows → Layers). A newly opened layer will be on top and selected for editing, indicated by the green tick mark next to it. Using Edit → Merge layer, you add its contents to the main map data (or any other layer you choose). You can then edit it further, add tags and upload it as described above. Note that merging layers cannot be reversed with the Edit → Undo function, so you may want to save to disk beforehand if you have already made some edits.

This functionality of JOSM works only with OpenStreetmap XML files. Though it can also open other file types, they cannot be merged and edited, so you would have to retrace them by hand (the most braindead kind of data conversion). For the GPS survey workflow to make sense, you have to convert your GPS tracks to OSM format. It is also advantageous to split the recorded track up into sections if you have been tracing multiple roads.

Theoretically, the tool GPSBabel is supposed to do that. It has never worked for me: I have encountered empty output, crashes, and tracks with a single point only, but never managed to convert a complete path. YMMV, so just try it out. The following paragraphs describe my workflow with the GPS logger I own, which leaves much scope for custom processing and will also be suitable for other devices with some modifications.

GPS surveying for OpenStreetmap with the Wintec WPL-2000 logger

The fun starts with obtaining the GPS data from the logger, as it is stored in a proprietary format and the enclosed software of course discriminates against free operating systems. With help from the information here, I have written a small Perl script that converts the binary data into a white space separated table of numbers. This generic output format allows to display and process it using general-purpose tools like gnuplot, awk or simple custom programs. The first column is the latitude; you will have to tell a generic plot program to use it for the vertical coordinate if you want a map-like display. My data extraction program puts any markers (if present) into the last column of the table. A new paragraph is started when the marker indicates that the logger was switched on or a new track was started.

GPS tracks can zig-zag a lot, especially when the fix is not perfect, such as in narrow valleys and dense forests. I sometimes use this Perl script to smooth the track. It reads from stdin or its file argument and writes to stdout. You may have to adapt it to your preferences, so have a look at the source if the results are not to your liking.

Finally the white space separated navigation data have to be converted to the OpenStreetmap XML format for JOSM. I have another Perl script for that here. (Perl is the most productive programming language I know, and is especially suitable for text processing.) Then one proceeds to merge the new path as described above.

[Aside: There is also a script for converting white space separated navigation data to KML format for Google Earth.]

Licensed under the Creative Commons Attribution-Share Alike 3.0 Germany License

TOS / Impressum