osmium-ruby

Disclaimer: This code was generated by Claude (Anthropic AI).

Ruby bindings for libosmium — read and write OpenStreetMap PBF files.

Requirements

Install system dependencies before building:

# Debian / Ubuntu
sudo apt install \
  libosmium2-dev \
  libprotozero-dev \
  libprotobuf-dev \
  zlib1g-dev \
  libbz2-dev \
  libexpat1-dev

Installation

gem 'osmium-ruby', git: 'https://github.com/teritorio/osmium-ruby.git'

Usage

Write a plain PBF file

require "osmium"

writer = Osmium::Writer.new("output.osm.pbf")
props = {
  "version" => 7,
  "visible" => true,
  "changeset" => 123456,
  "uid" => 42,
  "user" => "alice",
  "timestamp" => "2026-05-26T12:34:56Z"
}
writer.set_header("osmosis_replication_timestamp", Time.now.utc.iso8601)
writer.set_header("osmosis_replication_sequence_number", 1.to_s)
writer.set_header("osmosis_replication_base_url", "http://localhost/update/")
writer.add_node(1, props, 48.8566, 2.3522, { "name" => "Paris", "place" => "city" })
writer.add_node(2, props, 51.5074, -0.1278, { "name" => "London", "place" => "city" })
writer.add_way(100, props, [1, 2], { "highway" => "primary" })
writer.add_relation(
  200,
  props,
  [
    { "type" => "n", "ref" => 1, "role" => "capital" },
    { "type" => "w", "ref" => 100, "role" => "route" }
  ],
  { "type" => "route", "route" => "road" }
)
writer.close

set_header must be called before the first add_node / add_way / add_relation call. Calling it after writing has started raises a RuntimeError.

Read a PBF file

require "osmium"

data = Osmium::Reader.new("output.osm.pbf").read

data[:nodes].each { |n| puts "Node #{n[:id]}: #{n[:tags]}" }
data[:ways].each { |w| puts "Way  #{w[:id]}: nodes=#{w[:node_refs]}" }
data[:relations].each { |r| puts "Rel  #{r[:id]}: #{r[:tags]}" }

API reference

Osmium::Writer

Method	Description
Writer.new(path)	Open path for writing, no replication headers
Writer.new(path, timestamp, sequence_number, base_url)	Open with all three osmosis replication headers
set_header(key, value)	Set an arbitrary header field (before first write)
add_node(id, properties, lat, lon, tags)	Write a node
add_way(id, properties, node_refs, tags)	Write a way
add_relation(id, properties, members, tags)	Write a relation
close	Flush and close the file

Osmium::Reader

Method	Description
Reader.new(path)	Open path for reading
read	Return { nodes:, ways:, relations: } as Ruby Arrays of Hashes
header	Return the three osmosis replication header fields as a Hash

Building from source

git clone https://github.com/teritorio/osmium-ruby
cd osmium-ruby
bundle install
bundle exec rake compile
bundle exec rake spec

How it works

The gem is a native C++ extension (ext/osmium/osmium.cpp) that uses:

• Rice 4.x — C++ wrapper for Ruby's C API
• libosmium — header-only C++ library for OSM data I/O
• protozero — low-level protobuf encoder used by libosmium

The replication headers are stored in the PBF HeaderBlock via osmium::io::Header::set() and read back with osmium::io::Header::get(), matching exactly what osmium-tool writes with --output-header.

License

This code is released into the public domain (The Unlicense). You may use, copy, modify, and distribute it without restriction and without any warranty. See LICENSE for the full text.