Skip to content
C++/Javascript framework for working with OSM files.
C++ JavaScript Makefile Shell
Latest commit e2e4368 Apr 25, 2016 @joto Merge pull request #98 from xnox/master
Fix test-suite build failure.
Failed to load latest commit information.
debian Remove references to sqlite lib/Update README. Jun 18, 2013
examples Remove unused debug flag. Jul 8, 2013
include Bugfix: SparseTable index segfaulted when non-existing node was queried. Apr 28, 2015
osmjs Prefer prefix ++ to postfix ++ Jun 18, 2013
.gitignore gitignore cleanup Jul 25, 2011
Doxyfile updated Doxyfile with Doxygen 1.8.5 Sep 1, 2013
LICENSE-GPLv3 Switched license. Removed build of PBF stuff. Apr 13, 2011
Makefile Make install work on OS/X. See osmcode/libosmium#18 Apr 7, 2014
NOTES_FOR_DEVELOPERS Unify template formatting and naming of templare parameters Aug 20, 2012
THANKS Added THANKS file Mar 15, 2011 Change magic that finds libraries to compile with so it works with cl… May 7, 2013





   You almost certainly want the "new" Osmium at


Osmium is a C++ framework for working with OSM data files. Osmium can read OSM
data in XML or binary format (PBF) and can call different handlers for each OSM

Available handlers include:
* Javascript handler (calls Javascript callbacks you provide)
* Multipolygon handler (assembles areas(multipolygons) from relations and ways)
* NodeLocationStore handler (stores node locations and builds way geometries from them)
* ...

Of course, you can also write your own handlers.

There are a few applications that use Osmium in the examples directory.

The osmjs directory contains the osmjs application that calls your Javascript code
which can then work with the OSM data. It can, for instance, be used to convert
OSM data into Shapefiles.

Note that OSM input files must contain objects in the right order for Osmium to
work properly: first nodes, then ways, then relations. Normally OSM files are
sorted this way, but if yours aren't, you can use Osmosis with the --sort
option to do this.


Different parts of Osmium (and the applications built on top of it) need
different libraries:

boost (several libraries)
    Debian/Ubuntu: libboost-dev
    openSUSE: boost-devel

zlib (for PBF support)
    Debian/Ubuntu: zlib1g-dev
    openSUSE: zlib-devel

shapelib (for shapefile support in osmjs)
    Debian/Ubuntu: libshp-dev
    openSUSE: libshp-devel

libgd (for nodedensity example only)
    Debian/Ubuntu: libgd2-xpm-dev
    openSUSE: gd-devel

GDAL (for OGR support)
    Debian/Ubuntu: libgdal1-dev
    openSUSE: libgdal-devel

Expat (for parsing XML files)
    Debian/Ubuntu: libexpat1-dev
    openSUSE: libexpat-devel

GEOS (for assembling multipolygons etc.)
    Debian/Ubuntu: libgeos++-dev
    openSUSE: libgeos-devel

Google sparsehash
    Debian/Ubuntu: libsparsehash-dev
    openSUSE: sparsehash

Google V8 Javascript engine (for Javascript support)
    Osmium works with V8 version 3.14 and 3.15, but not with 3.21.
    Debian/Ubuntu: libv8-dev
    openSUSE: v8-devel

LibICU (for UTF-8/UTF-16 conversion, only for Javascript support)
    Debian/Ubuntu: libicu-dev
    openSUSE: libicu-devel

Google protocol buffers (for PBF support) (at least version 2.3.0 needed)
    Debian/Ubuntu: libprotobuf-dev protobuf-compiler
    openSUSE: protobuf-devel
    Also see

Doxygen (to build API documentation)
    Debian/Ubuntu: doxygen

libboost-test (for tests)
    Debian/Ubuntu: libboost-test-dev

OSMPBF (for PBF support)
    Debian/Ubuntu: libosmpbf-dev

You need to either install the packages for your distribution or install those
libraries from source. Most libraries should be available in all distributions.


Doxyfile    - Needed for building the Osmium C++ docs, call "make doc" to build.
include     - C/C++ include files. All of Osmium is in those header files which
              are needed for building Osmium applications.
osmjs       - Osmium application "osmjs".
osmjs/js    - Example Javascript handlers.
examples    - Osmium example applications.
test        - Tests (see below).
debian      - Needed to build Debian/Ubuntu packages.


First you need to (build and) install all the prerequisites.

Osmium is a header-only library, so there is nothing to build for the
library itself.

Call "make doc" in the top-level directory to build the Osmium C++ docs.

Call "make install" to install the include files and documentation.

See "examples/README" for build instructions of the example applications.

See "osmjs/README" for build instructions of osmjs.

Call "make clean" in any of those places to clean up.


To use Osmium in your code you just have to include the headers you are
interested in. So, if you need the Way class for instance you include
<osmium/osm/way.hpp>. If you need the Debug handler, you include

If you need any OSM file input, then first define one or both of these macros
and then include <osmium.hpp>:

  #include <osmium.hpp>

There are some parts of Osmium that are a bit more difficult to use.
You'll find some examples in the 'example' and 'osmjs' directories.


There are a few tests using the Boost Unit Test Framework in the "test"
directory. Many more tests are needed, any help appreciated.

Run "make test" from the main directory or go to the "test" directory and type
"./" to compile and run the tests. You can run a single test by
calling "./ TESTFILE", for instance:
  ./ t/osm/test_node.cpp

There are some other tests that are not neatly integrated. Go to the "test"
directory and run


Osmium is available under the GNU LGPL version 3 or later, or - at your option -
the GNU GPL version 3 or later.

See for a
good description of what that means.


Osmium was mainly written and is maintained by Jochen Topf <>.

Other authors:
* Frederik Ramm <> (Multipolygon code, ...)
* Christian Vetter <> (PBF parser)
* Scott A. Crosby <> (PBF format)
* Peter Körner <> (XML and PBF writer, ...)
* Johannes Kolb <> (Tests, ...)

Something went wrong with that request. Please try again.