OSM2PostGIS Project Web

For developers and advanced users

For now, often the best way to understand OSM2PostGIS is by trial and error and by reading the self-documenting source code.


Many of the OSM2PostGIS software features have not found a stable form yet. Writing comprehensive documentation for the unfinished design would require continuous maintenance. More documentation will be added as the project matures.


The software versions stated below are tested to work with the current version of OSM2PostGIS. It may or may not work with earlier or later versions of the same (or compatible) software. Especially newer versions should work (even better than the tested versions), but there is no guarantee.

If you want to use an environment similar to what the author of OSM2PostGIS is using right now, please observe the component choices and version numbers below.

Configuration, compilation and installation instructions for all the dependencies are found on their web sites or inside their distribution packages.

CentOS distribution packages are installed using YUM as usual.

More detailed instructions for the dependencies may be added later. If you can't or don't want to install the dependencies yourself, you probably wouldn't want to use osm2postgis either in its current shape. Please come back at a later time when the product has matured. We appreciate your interest in the project, however regrettably are unable to serve any production ready distributions at this time.

TODO: Collect the links to installation instructions below.

Database server

The host machine that runs the PostGIS spatially-enabled database

  • Stores the desired geometry data and routing network topology (as relational tuples) that is the output

The dependencies below are listed assuming that you are going to compile and install many of the packages from sources. If you are compiling on a different host, most of these dependencies are actually for the host where you compile the server-side packages.

TODO: Separate compile- and run-time dependencies.

  1. CentOS release 5.4 (Final) Linux 2.6.18-164.11.1.el5xen x86_64
  2. PostgreSQL 8.1.18 server (CentOS postgresql-server.x86_64)
  3. PostgreSQL 8.1.18 development headers (CentOS postgresql-devel.x86_64)
  4. Flex: The Fast Lexical Analyzer 2.5.4 (CentOS flex.x86_64)
  5. Boost C++ Libraries 1.33.1 (CentOS boost-devel.x86_64)
  6. PROJ.4 Cartographic Projections Library (proj-4.7.0)
  7. Geometry Engine - Open Source (geos-3.2.0)
  8. Subversion (CentOS subversion.x86_64)
  9. PostGIS 1.3.6
  10. Genetic Algorithm Utility Library (gaul-devel-0.1849-0)
  11. CMake build system (cmake-2.8.0)
  12. pgRouting 1.03

You will want to install the PROJ.4 and GEOS libraries before installing PostGIS.

TODO: Please report any missing dependencies.

Client host

The host machine that runs the osm2postgis program

  • Has access to a copy of the OpenStreetMap source data that is the input (.osm XML files)

So far, the OSM data for Malta and Iceland have been used for testing—because both are comfortably small.

  1. Sun Java SE 6 JRE (or JDK)
  2. PostgreSQL JDBC4 driver (postgresql-8.4-701.jdbc4.jar)
  3. PostGIS JDBC extension (postgis_1.3.6.jar)
  4. OSM2PostGIS executable (OSM2PostGIS-0.0.0.*.jar)

Development host

Where you compile and build the OSM2PostGIS package (This may be the same machine as the client host.)

  1. Ubuntu 9.10 karmic Linux 2.6.31-16-generic #53-Ubuntu SMP x86_64
  2. PostgreSQL 8.4.2 client applications (Ubuntu postgresql-client)
  3. Java SE 6 JDK (Ubuntu sun-java6-jdk)
  4. JArgs 1.0 http://jargs.sourceforge.net/ (comes with OSM2PostGIS source)
  5. JSON in Java http://www.json.org/java/ (comes with OSM2PostGIS source)
  6. bunzip2
  7. Java Secure Channel (jsch-0.1.42.jar for Ant to use some targets)
  8. SvnAnt 1.3.0 http://subclipse.tigris.org/svnant.html
  9. Apache Ant 1.7.1


Working on the development host, go to the directory where you extracted the OSM2PostGIS package (or checked out the trunk from the Subversion repository):

$ cd osm2postgis

Run Ant:

$ ant

If Ant cannot find the geometry classes, it means that the PostGIS JDBC extension JAR is missing from the Java class path.

When the build is successful, it produces the OSM2PostGIS JAR in the dist/lib/ subdirectory, e.g.:


Configuration and usage

Map feature specification

OSM2PostGIS makes it quite easy to generate almost any kind of database you like from the OSM data. You can design the table names, column names, and specify which map features go into which tables and are associated with which attributes. You can create as many tables you like with as many columns you like, be it only one or dozens. All the target tables can be similar or they can be entirely different. It's up to you to decide what kind of data you want.

The default features.json file that comes with current OSM2PostGIS (in the conf/ directory) contains rough instructions on how to to configure map feature recognition. A better tutorial on that will be written later.

Command line interface

Ensure that the compiled class files and the client dependencies are in the Java class path:

  • OSM2PostGIS-<version>.jar
  • postgresql-8.4-701.jdbc4.jar
  • postgis_1.3.6.jar

Run the program from the command line:

$ java net.sourceforge.osm2postgis.Shell -d host:port/database planet.osm

Alternatively, you can use a similar Eclipse run configuration.

For example, in the current test environment the database server hostname is "kanta" (using the default port 5432) and the PostGIS database name is "routing", so:

$ java net.sourceforge.osm2postgis.Shell -d kanta/routing malta.osm

If you need to specify a database password, you can do so by adding the -W option. However, please keep in mind that the password given on the command line is not masked. Also storing passwords in plain text files is a security risk. Even if you are not writing a script, your operating system shell may automatically store the whole command line—including the password—in command line history. Usually it's a better idea to use some other authentication method, for example PostgreSQL 'ident' authentication.

You can also add the -s option to set the number of lines to be skipped from the start of the file. This is useful, if you want to continue an interrupted import.

The -p option sets which process phases are run. The choices are "changesets, nodes, ways, relations, topology, features" that must be a comma-separated list. If there are spaces, the list must be enclosed in double quotes. Only the first letter of each keyword is required. E.g. to only create topology and geometry for rendering, use:

Shell -p t,f

To only import nodes without overwriting any other data, use:

Shell -p n

Note that you must import nodes before importing any ways referring to those nodes. Similarly you must import all ways and nodes before any relations referring to those ways and nodes.

If you import a larger area to an existing database, remember to recalculate the layer bounds in GeoServer.

The -f option sets the location of the feature specification file for map feature recognition. The default name is "features.json" in the current directory.

Using the resulting data

The relational model

TODO: Explain the tables


TODO: Configuring GeoServer, writing SLD's


TODO: pgRouting queries