Skip to content

An OpenStreetMap pbf parser which exports json, allows you to cherry-pick tags and handles denormalizing ways and relations. Available as a standalone binary and comes with a convenient npm wrapper.



Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time
April 13, 2015 18:29
August 21, 2019 08:16
June 8, 2016 14:29
April 13, 2015 18:29
November 2, 2018 11:47
July 22, 2021 02:31
July 22, 2021 02:31
September 23, 2021 11:34

pbf2json creates a JSON stream of openstreetmap data from any PBF extract, you can pick-and-choose only the bits of the file you want, the library will take care of de-normalizing the relational data (nodes/ways/relations) so you can put it straight in to your favourite document-store, inverted index or graph database.


Run from pre-built binary

Greenkeeper badge

You don't need to have Go installed on your system to use one of the precompiled binaries in ./build:

# AMD 64-bit linux/macOS/windows
$ ./build/pbf2json.linux-x64
$ ./build/pbf2json.darwin-x64
$ ./build/pbf2json.win32-x64

# ARM 64-bit linux/macOS
$ ./build/pbf2json.linux-arm64
$ ./build/pbf2json.darwin-arm64


To control which tags are output you must pass the -tags= flag to pbf2json and the PBF filepath:

$ ./build/pbf2json.linux-x64 -tags="amenity" /tmp/wellington_new-zealand.osm.pbf
{"id":170603342,"type":"node","lat":-41.289843000000005,"lon":174.7944402,"tags":{"amenity":"fountain","created_by":"Potlatch 0.5d","name":"Oriental Bay Fountain","source":"knowledge"},"timestamp":"0001-01-01T00:00:00Z"}
{"id":170605346,"type":"node","lat":-41.2861039,"lon":174.7711539,"tags":{"amenity":"fountain","created_by":"Potlatch 0.10c","source":"knowledge"},"timestamp":"0001-01-01T00:00:00Z"}

Advanced Usage

Multiple tags can be specified with commas, records will be returned if they match one OR the other:

# all buildings and shops

Tags can also be grouped with the + symbol, records will only be returned if they match one AND the other:

# only records with BOTH housenumber and street specified

You can also combine the above 2 delimiters to get even more control over what get's returned:

# only highways and waterways which have a name

If you need to target only specific values for a tag you can specify exactly which values you wish to extract using the ~ symbol:

# only extract cuisine tags which have the value of vegetarian or vegan


When processing the ways, the node refs are looked up for you and the lat/lon values are added to each way.

Since version 3.0 centroids are also computed for each way, since version 5.0 bounds are now also computed.

Output of the nodes array (as seen below) is optional, this was disabled by default in version 5.0 but can be enabled with the flag --waynodes=true.

  "id": 301435061,
  "type": "way",
  "tags": {
    "addr:housenumber": "33",
    "addr:postcode": "N5 1TH",
    "addr:street": "Highbury Park",
    "building": "residential"
  "centroid": {
    "lat": "51.554679",
    "lon": "-0.098485"
  "bounds": {
    "e": "-0.0983673",
    "n": "51.5547179",
    "s": "51.5546574",
    "w": "-0.0985915"
  "nodes": [
      "lat": "51.554663",
      "lon": "-0.098369"
      "lat": "51.554657",
      "lon": "-0.098529"
      "lat": "51.554656",
      "lon": "-0.098592"
      "lat": "51.554676",
      "lon": "-0.098590"
      "lat": "51.554680",
      "lon": "-0.098529"
      "lat": "51.554715",
      "lon": "-0.098529"
      "lat": "51.554720",
      "lon": "-0.098369"
      "lat": "51.554663",
      "lon": "-0.098369"


Since version 6.0 centroids and bounding boxes are also computed for relations, the calulations are based off the largest member way by area.

Note: if a relation does not contain at least one way then it will not be output.


This library uses leveldb to store the lat/lon info about nodes so that it can denormalize the ways for you.

By default the leveldb path is set to /tmp, you can change where it stores the data with a flag:

$ ./build/pbf2json.linux-x64 -leveldb="/tmp/somewhere"

Batched writes

Since version 3.0 writing of node info to leveldb is done in batches to improve performance.

By default the batch size is 50000, you can change this with the following flag:

$ ./build/pbf2json.linux-x64 -batch="1000"

NPM module

var pbf2json = require('pbf2json'),
    through = require('through2');

var config = {
  file: '/tmp/wellington_new-zealand.osm.pbf',
  tags: [
  leveldb: '/tmp'

pbf2json.createReadStream( config )
 .pipe( through.obj( function( item, e, next ){
    console.log( item );

Run the go code from source

Make sure Go is installed and configured on your system, see:

Note: You should install the latest version of Golang, at least 1.5+, last tested on 1.6.2

sudo apt-get install mercurial;
go get;
go run pbf2json.go;

Compile source for all supported architecture

If you are doing a release and would like to compile for all supported architectures:

note if this is your first time doing this please read the notes in './' to set it all up on your machine.


Compile source for a new architecture

If you would like to compile a version of this lib for an architecture which isn't currently supported you can:

go get;
go build;
chmod +x pbf2json;
mv pbf2json build/pbf2json.{platform}-{arch};

Note you will need to change the variables {platform} and {arch} to match those returned by nodejs for your system:

$ node
> var os=require('os')
> os.platform()
> os.arch()

Then submit a pull request, you are awesome ;)


An OpenStreetMap pbf parser which exports json, allows you to cherry-pick tags and handles denormalizing ways and relations. Available as a standalone binary and comes with a convenient npm wrapper.



Code of conduct





No packages published