osm4j is a Java library for working with OpenStreetMap data. Our first attempts of using OSM data on the Java platform were based on Osmosis. The callback-driven style of programming didn't feel very comfortable however, so that we decided to write our own abstraction layer.

Our library provides abstract data types for representing OSM data and iterative input and output handlers for various common file formats. In addition, callback-based handlers are also available so that programs written in this style can easily be ported.

It also provides support for processing and manipulating the geometry of OSM objects by providing bindings to the data structures from JTS.

Table of contents


osm4j is released under the terms of the GNU Lesser General Public License version 3 (GNU LGPLv3).

Source code

The source code is available on our GitHub page. Please report issues there. The following repositories belong to osm4j: osm4j-core, osm4j-geometry, osm4j-xml, osm4j-pbf, osm4j-tbo, osm4j-utils, osm4j-extra, osm4j-examples, osm4j-incubating


To learn how to use osm4j have a look a the Tutorial.

There is a collection of examples on GitHub that includes the code used in the tutorial and more.

There is also Javadoc available for all artifacts: osm4j-core, osm4j-xml, osm4j-pbf, osm4j-tbo, osm4j-geometry, osm4j-utils, osm4j-extra

There is also a page about osm4j on the OpenStreetMap wiki.

Should you have any questions, get in touch using the Mailing List

Package overview

The library consists of a few modules that package related functionality, so that you can easily select just those components that you need:


osm4j provides the basic interfaces and data types for representing objects from the OpenStreetMap. Additionally, it provides common interfaces and data handlers for reading OSM data as well as some useful utility methods that make some basics operations on the data easy to accomplish.


osm4j-xml contains input and output methods for the basic XML representation of OSM data. By using a third party compression library such as Apache Commons Compress, for filtering input and output streams, it can also be used to process gzip or bzip2 compressed data.


osm4j-pbf provides the tools for working with the very widely used PBF file format for OSM data that is based on Google's Protocol Buffers.


osm4j-tbo can be used to read and write our own binary OSM file format. The file format is very similar to PBF, but is not based on Protocol Buffers. It has been designed to offer similar compression while offering enhanced access methods and to allow for improved I/O performance.


osm4j-geometry is a package for making it easy to perform geometric operations with OpenStreetMap data. It contains utilities for converting the basic types of elements defined in the OSM data model to their geoemtric representations. It uses the JTS Topology Suite to represent geometric objects, which allows you to apply a number of typical GIS operations to your data.


osm4j-utils is a collection of command line tools for performing recurring tasks on OSM data such as conversion between different file formats. It also provides some tools for data analyis.

The classes of this package can also be used as helpful utilities when implementing custom data manipulation tasks.


Maven / Gradle

All packages are available through a public Maven repository. Add the following repository to your build.gradle file:


It contains the following artifacts that you can add as dependencies:

compile 'de.topobyte:osm4j-core:0.0.20'
compile 'de.topobyte:osm4j-utils:0.0.23'
compile 'de.topobyte:osm4j-xml:0.0.5'
compile 'de.topobyte:osm4j-pbf:0.0.10'
compile 'de.topobyte:osm4j-tbo:0.0.10'
compile 'de.topobyte:osm4j-geometry:0.0.15'

Basic usage

This snippet shows basic usage of the library:

  public static void main(String[] args) throws IOException
    // Define a query to retrieve some data
    String query = "http://www.overpass-api.de/api/xapi?*[bbox="
        + "13.465661,52.504055,13.469817,52.506204]";
    // Open a stream
    InputStream input = new URL(query).openStream();
    // Create a reader for XML data
    OsmIterator iterator = new OsmXmlIterator(input, false);
    // Iterate contained entities
    for (EntityContainer container : iterator) {
      // Only use nodes
      if (container.getType() == EntityType.Node) {
        // Get the node from the container
        OsmNode node = (OsmNode) container.getEntity();
        // Convert the node's tags to a map
        Map<String, String> tags = OsmModelUtil.getTagsAsMap(node);
        // Get the value for the 'amenity' key
        String amenity = tags.get("amenity");
        // Check if this is a restaurant
        boolean isRestaurant = amenity != null
            && amenity.equals("restaurant");
        // If yes, print name and coordinate
        if (isRestaurant) {
          System.out.println(String.format("%s: %f, %f",


Salt & Pepper: 52.505004, 13.468952
Rancho Grande: 52.505088, 13.469047
Sonntag: 52.505548, 13.466235
Pho' House: 52.504662, 13.468620
Imaki Sushi: 52.504752, 13.468703
Transit: 52.505967, 13.465723
VIETBOWL: 52.505787, 13.466867
Caminetto: 52.505206, 13.467177
Hot 'n' Spicy Food: 52.504850, 13.467597
Glory Duck: 52.505631, 13.466148
Bettenhaus: 52.505474, 13.466318