osmium - Processing OSM files

Osmium processes files by reading data from a file and applying them to a processing chain. Pyosmium offers a simplified wrapper to this interface with the SimpleHandler class from which an OSM file processor can easily be derived.

For more fine grained control of the processing chain, the more basic functions and processors are exported as well in this module.

Input Handlers

An input handler implements provides the base class for writing custom data processors. They take input data, usually from a file, and forward it to handler functions.

class osmium.SimpleHandler

The most generic of OSM data handlers. For each data type a callback can be implemented where the object is processed. Note that all objects that are handed into the handler are only readable and are only valid until the end of the callback is reached. Any data that should be retained must be copied into other data structures.

apply_buffer((SimpleHandler)self, (object)buffer, (str)format[, (bool)locations=False[, (str)idx='sparse_mem_array']]) → None :

Apply the handler to a string buffer. The buffer must be a byte string.

apply_file((SimpleHandler)self, (str)filename[, (bool)locations=False[, (str)idx='sparse_mem_array']]) → None :

Apply the handler to the given file. If locations is true, then a location handler will be applied before, which saves the node positions. In that case, the type of this position index can be further selected in idx. If an area callback is implemented, then the file will be scanned twice and a location handler and a handler for assembling multipolygones and areas from ways will be executed.

area((SimpleHandler)self, (Area)area) → None :

Handler called for area objects.

area( (SimpleHandler)self, (Area)area) -> None

changeset((SimpleHandler)self, (Changeset)changeset) → None :

Handler called for changeset objects.

changeset( (SimpleHandler)self, (Changeset)changeset) -> None

node((SimpleHandler)self, (Node)node) → None :

Handler called for node objects.

node( (SimpleHandler)self, (Node)node) -> None

relation((SimpleHandler)self, (Relation)relation) → None :

Handler called for relation objects.

relation( (SimpleHandler)self, (Relation)relation) -> None

way((SimpleHandler)self, (Way)way) → None :

Handler called for way objects. If the geometry of the way is needed then locations must be set to true when calling apply_file.

way( (SimpleHandler)self, (Way)way) -> None


The writer class can be used to create an OSM file. The writer is able to handle native osmium.osm objects as well as any Python object that exposes the same attributes. It is not necessary to implement the full list of attributes as any missing attributes will be replaced with a sensible default value when writing. See Mutable OSM Objects for a detailed discussion what data formats are understood for each attribute.


Writers are considerably faster in handling native osmium data types than Python objects. You should therefore avoid converting objects whereever possible. This is not only true for the OSM data types like Node, Way and Relation but also for tag lists, node lists and member lists.

class osmium.SimpleWriter

The most generic class to write osmium objects into a file. The writer takes a file name as its mandatory parameter. The file must not yet exists. The file type to output is determined from the file extension. The second (optional) parameter is the buffer size. osmium caches the output data in an internal memory buffer before writing it on disk. This parameter allows changing the default buffer size of 4MB. Larger buffers are normally better but you should be aware that there are normally multiple buffers in use during the write process.

add_node((SimpleWriter)self, (object)node) → None :

Add a new node to the file. The node may be an osmium.osm.Node object, an osmium.osm.mutable.Node object or any other Python object that implements the same attributes.

add_relation((SimpleWriter)self, (object)relation) → None :

Add a new relation to the file. The relation may be an osmium.osm.Relation object, an osmium.osm.mutable.Way object or any other Python object that implements the same attributes.

add_way((SimpleWriter)self, (object)way) → None :

Add a new way to the file. The way may be an osmium.osm.Way object, an osmium.osm.mutable.Way object or any other Python object that implements the same attributes.

close((SimpleWriter)self) → None :

Flush the remaining buffers and close the writer. While it is not strictly necessary to call this function explicitly, it is still strongly recommended to close the writer as soon as possible, so that the buffer memory can be freed.

Low-level Functions and Classes

osmium.apply((Reader)arg1, (SimpleHandler)arg2) → None :

Apply a chain of handlers.

apply( (Reader)arg1, (NodeLocationsForWays)arg2) -> None

apply( (Reader)arg1, (NodeLocationsForWays)arg2, (SimpleHandler)arg3) -> None