From OpenStreetMap Wiki
Jump to: navigation, search
This article is about the Java program for converting shapefiles for imports. For alternative methods see Import/Shapefile.
Screenshot of Shp-to-osm.jar
Author: Ian Dees
License: GNU General Public License
Version: 0.8.2 (2010-05-08)
Language: English
Source code: shp-to-osm-0.8.1-jar-with-dependencies.jar
Programming language: Java

Easy to use, nice UI

The shp-to-osm.jar program is a conversion utility program made by Ian Dees.

You can download it from (please submit bugs using the above website)

Usage: It uses as simple RULES.txt file which can be edited to reflect the columns that exist in the .dbf file.

Examples: Currently this utility is used by user:Acrosscanadatrails for canvec-to-osm to convert the Natural Resources Canada, Geogratis datasets of CanVec, and the NRCan, GeoBase datasets of National Hydrography network GeoBaseNHN2osm, and others.

shp-to-osm.jar Usage

java -cp shp-to-osm-0.8.1-with-dependencies.jar com.yellowbkpk.geo.shp.Main
    --shapefile <path to input shapefile> \
    --rulesfile <path to rules file> \
    --osmfile <prefix of the output osm file name> \
    [--outdir <root directory for output>] \
    [--outputFormat <osm|osmc>] \
    [--maxnodes <max nodes per osm file>] \
    [--glomKey <key to glom on (see README)>] \

When running from the command prompt in Windows, you need to put quotes around path names that contain spaces, or use abbreviated names which can be obtained by dir /x.

As of version 0.7.3 all file names contain an index, between the prefix and the osm extension. This index starts with 0.

Example: java -cp C:\maps\shp-to-osm-0.8.1-jar-with-dependencies.jar com.yellowbkpk.geo.shp.Main --shapefile C:\maps\map.shp" --rulesfile "C:\shp-to-osm\rulesstanwater.txt --osmfile C:\maps\maps.osm -t 50000.


  • In 0.4.1, there is a limit of 50000 nodes by generated files. output.osm0.osm, output.osm1.osm, output.osm2.osm will be generated.
  • Despite the limit of 2000 points, certain OSM files can be larger. This happens when features contain many nodes. This is especially true for (large) multipolygon relations.
  • 0.7 creates xml files instead of osm files

Rules TXT

Rules text shouldn't add "type" <key>, because relation automatically add type="multipolygon".

Columns name can be fetched by opening .dbf files. Inside by example.

Field: Description:

1 The shapefile type to match (outer, inner, line, point) (see below)

2 The source attribute name to match

3 The source attribute value to match. Can be empty to match all values.

4 The name of the tag to apply when the source key/value pair match.

5 The value of the tag to apply. Use a sinlgle dash ("-") to use the original value.

Create a file named RULES.TXT using a plain text editor such as Windows Notepad. The file MUST NOT contain empty lines; it may contain comment lines that begin with the "#" character.

For example:



If the source file is polygons then use.


If then source file is lines then use


and if the source file is points then use.


In the example above, "TYPE_TEXT" is listed as the heading in row one of the .dbf file, and "Canal" is listed as one of the options in rows 2 to however many there are. and the OSM Key, that we use for "TYPE_TEXT" is "waterway" and the OSM Value that we use for "Canal" is "canal".

Please note that attributes in Shapefiles are case sensitive and the rules.txt needs to match the case of the DBF columns.

Sample rule sets:

USA National Hydrography Dataset NHD_Rules

USA tiger, a sample work in progress shp-to-osm/tiger-rules.txt


As of shp-to-osm 0.7, the applications supports what the author calls "glomming": the ability to connect ways that share some key/value pair. The command line argument --glomKey specifies a single OSM tag name that should be used when checking for matches. It is important to note that the glom key is an OSM tag name, not a shapefile attribute name. The tag must be created by your rulesfile or it won't be useable as a glomming key.

For example, if my shapefile has a large river system where each segment of river is split at the point where rivers come together, then we can use glomming to connect the ways of rivers that share similar name (or in the case of NHD data, reachcode) values.

Compiling shp-to-osm

(tried on Ubuntu Jaunty and Karmic as well as Windows XP)

Maven is used to download dependencies. Eclipse has a Maven plugin that will download the required JARs and setup the project for you:

# apt-get install eclipse
$ git clone git://
$ git clone git://

$ eclipse
Help > Install New Software...
   Paste in "" "Work with:" text box. Hit enter.
   Select Maven Integration > Maven Integration for Eclipse
   Install it and restart Eclipse
File > Import > Maven Project # find shp-to-osm folder...
Window > Properties... > Java > Installed JRES > Add... /usr/lib/usr/lib/jvm/java-6-openjdk/ # unselect 1.5, select java-6