azavea / topobuf

Topobuf

Topobuf is a compact binary encoding for topological data.

Topobuf provides lossless¹ compression of TopoJSON data into protocol buffers. Advantages over using JSON-based formats alone:

• Very compact: typically makes TopoJSON 2-3 times smaller.
• Smaller even when comparing gzipped sizes: 20-30% for TopoJSON.
• Can store topology objects too large for JSON.stringify / JSON.parse
• Can accommodate any TopoJSON data, including extensions with arbitrary properties.

Sample compression sizes

	normal	gzipped
pa-census-blocks.json	280 MB	44 MB
pa-census-blocks.pbf	114 MB	35 MB
us-zips.json	15.02 MB	3.19 MB
us-zips.pbf	4.85 MB	2.72 MB
idaho.json	1.9 MB	612 KB
idaho.pbf	567 KB	479 KB

Install

npm install topobuf

API

encode

var buffer = topobuf.encode(topojson, new Pbf());

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

decode

var topojson = topobuf.decode(new Pbf(data));

Given a Pbf object with topobuf data, return a TopoJSON object.

See more

This library is based on geobuf by Mapbox, which provides similar functionality for GeoJSON

Footnotes

1. When using quantized TopoJSON - nearly lossless otherwise ↩