geobuf

Compact binary encoding for geographic data

Geobuf

Geobuf is a compact binary encoding for geographic data.

Geobuf provides lossless compression of GeoJSON and TopoJSON data into protocol buffers. Advantages over using JSON-based formats alone:

  • Very compact: typically makes GeoJSON 6-8 times smaller and TopoJSON 2-3 times smaller.
  • Smaller even when comparing gzipped sizes: 2-2.5x compression for GeoJSON and 20-30% for TopoJSON.
  • Very fast encoding and decoding — even faster than native JSON parse/stringify.
  • Can accommodate any GeoJSON and TopoJSON data, including extensions with arbitrary properties.

The encoding format also potentially allows:

  • Easy incremental parsing — get features out as you read them, without the need to build in-memory representation of the whole data.
  • Partial reads — read only the parts you actually need, skipping the rest.

Think of this as an attempt to design a simple, modern Shapefile successor that works seamlessly with GeoJSON and TopoJSON. Unlike Mapbox Vector Tiles, it aims for lossless compression of datasets — without tiling, projecting coordinates, flattening geometries or stripping properties.

                | normal    | gzipped

------------------- | --------- | -------- us-zips.json | 101.85 MB | 26.67 MB us-zips.pbf | 12.24 MB | 10.48 MB us-zips.topo.json | 15.02 MB | 3.19 MB us-zips.topo.pbf | 4.85 MB | 2.72 MB idaho.json | 10.92 MB | 2.57 MB idaho.pbf | 1.37 MB | 1.17 MB idaho.topo.json | 1.9 MB | 612 KB idaho.topo.pbf | 567 KB | 479 KB

var buffer = geobuf.encode(geojson, new Pbf());

Given a GeoJSON or TopoJSON object and a Pbf object to write to, returns a Geobuf as a Buffer object in Node or UInt8Array object in browsers.

var geojson = geobuf.decode(new Pbf(data));

Given a Pbf object with Geobuf data, return a GeoJSON or TopoJSON object.

Node and Browserify:

npm install geobuf

Making a browser build:

npm install
npm run build-dev # dist/geobuf-dev.js (development build)
npm run build-min # dist/geobuf.js (minified production build)
npm install -g geobuf

Installs these nifty binaries:

  • geobuf2json: turn Geobuf from stdin or specified file to GeoJSON/TopoJSON on stdout
  • json2geobuf: turn GeoJSON or TopoJSON from stdin or specified file to Geobuf on stdout
  • shp2geobuf: given a Shapefile filename, send Geobuf on stdout
json2geobuf data.json > data.pbf
shp2geobuf myshapefile > data.pbf
geobuf2json data.pbf > data.json
  • geojsonp — the prototype that led to this project
  • twkb — a geospatial binary encoding that doesn't support topology and doesn't encode any non-geographic properties besides id
  • vector-tile-spec
  • topojson — an extension of GeoJSON that supports topology
  • WKT and WKB — popular in databases. Not an open standard.
  • EWKB is a popular superset of WKB.