Contributing to OpenStreetmap
Other docs --
Map features --
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
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
further docs, but they are controlled by Google Docs and download protected by
The OpenStreetmap wiki also contains more
information on contributing than on any other topic. There is an
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
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:
- Learn English, with correct spelling. Get a dictionary if you are a
non-native speaker, an American or a dog. No standard software is going to
make use of "building: Nersing Home" or "building: ბაზილიკა, ერთნავიანი.".
- Understand what information a tag is supposed to contain before you use it.
"building: manhole cover" is useless except as a good laugh, and house
numbers do not go into the building tag either.
- Stick to frequently-used tag values listed in the wiki rather than
inventing new ones. Most tag values are not printed on a rendered map, but
interpreted by automatic software whose authors have no knowledge of your
- Do not add more specific information than the tag is intended for. Use
additional tags if you have to but be aware that standard software is only
going to care about frequently available information either way.
- Do not put capital letters (except in names), "fixme", lists of values,
single letters, question marks or cryptic letter-digit combinations in tag
Editing paths --
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
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.
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
- 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
- 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),
- 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
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
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