topobuf

Compact binary encoding for topojson data

Usage no npm install needed!

<script type="module">
  import topobuf from 'https://cdn.skypack.dev/topobuf';
</script>

README

Topobuf

Build Status

Topobuf is a compact binary encoding for topographic data.

Topobuf provides lossless[^1] 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

[^1]: When using quantized TopoJSON - nearly lossless otherwise