# geobuf > Compact binary encoding for geographic data Latest version **4.0.0** (published 2026-04-28) · ISC license · 0 weekly downloads ## Install ```sh npm install geobuf pnpm add geobuf yarn add geobuf bun add geobuf ``` Provides the commands `shp2geobuf`, `geobuf2json`, `json2geobuf`. ## Health **Score 58/100 (C)** — status: active. Positive: has types package; esm support; no vulnerabilities; high quality score. Warnings: low downloads. ## Facts | | | |---|---| | Version | 4.0.0 | | Published | 2026-04-28 | | First published | 2014-07-16 | | Weekly downloads | 0 | | License | ISC | | TypeScript types | separate (@types/geobuf) | | Module format | ESM + CommonJS | | Dependencies | 2 | | Unpacked size | 56.3 KB | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 1033 | | Maintainers | mapbox-npm-01, mapbox-npm-02, mapbox-npm-07, mapbox-npm-03, mapbox-npm-04, mapbox-npm-09, mapbox-npm-05, mapbox-npm-06, mapbox-npm-08, mapbox-npm-advanced-actions, mapbox-npm-ci, mapbox-npm, mapbox-admin, mapbox-machine-user, mbx-npm-ci-staging, mbx-npm-ci-production, mbx-npm-01-production, mbx-npm-02-production, mbx-npm-03-production, mbx-npm-04-production, mbx-npm-05-production, mbx-npm-06-production, mbx-npm-07-production, mbx-npm-08-production, mbx-npm-09-production, mbx-npm-02-staging, mbx-npm-advanced-actions-staging, mbx-npm-advanced-actions-production | | Keywords | geographic, data, buffer, protobuf, format, compression, geojson, topojson | ## Links - npm: https://www.npmjs.com/package/geobuf - Repository: https://github.com/mapbox/geobuf - Issues: https://github.com/mapbox/geobuf/issues - npm.io page: https://npm.io/package/geobuf ## Dependencies (2) - [pbf](https://npm.io/package/pbf.md) ^4.0.1 - [shapefile](https://npm.io/package/shapefile.md) ~0.6.6 ## Alternatives - [@libsql/sqlite3](https://npm.io/package/@libsql/sqlite3.md) — 39.8K weekly downloads - [@fortemi/core](https://npm.io/package/@fortemi/core.md) — 461 weekly downloads - [cdb-converter](https://npm.io/package/cdb-converter.md) — 341 weekly downloads - [@uplo/adapter-prisma](https://npm.io/package/@uplo/adapter-prisma.md) — 75 weekly downloads - [typeorm-aios](https://npm.io/package/typeorm-aios.md) — 30 weekly downloads ## Recent versions - 4.0.0 (latest) — 2026-04-28 - 3.0.2 — 2020-07-20 - 3.0.1 — 2018-07-27 - 3.0.0 — 2016-09-20 - 0.2.5 — 2016-06-27 - 2.0.0 — 2016-02-05 - 1.0.2 — 2016-02-05 - 0.2.4 — 2015-03-22 - 1.0.1 — 2015-01-12 - 1.0.0 — 2015-01-10 - 0.2.3 — 2014-11-07 - 0.2.2 — 2014-09-10 - 0.2.1 — 2014-07-29 - 0.2.0 — 2014-07-29 - 0.1.2 — 2014-07-24 - … 2 more at https://npm.io/package/geobuf/versions ## README # Geobuf Geobuf is a compact binary encoding for geographic data. Geobuf provides _nearly lossless_ compression of GeoJSON data into [protocol buffers](https://developers.google.com/protocol-buffers/). Advantages over using GeoJSON alone: - **Very compact**: typically makes GeoJSON 6-8 times smaller. - 2-2.5x smaller even when comparing gzipped sizes. - **Very fast encoding and decoding** — even faster than native JSON parse/stringify. - Can accommodate any GeoJSON data, including extensions with arbitrary properties. The [encoding format](geobuf.proto) 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. Unlike [Mapbox Vector Tiles](https://github.com/mapbox/vector-tile-spec/), it aims for nearly lossless compression of datasets — without tiling, projecting coordinates, flattening geometries or stripping properties. Note that the encoding schema is **not stable yet** — it may still change as we get community feedback and discover new ways to improve it. "Nearly" lossless means coordinates are encoded with precision of 6 digits after the decimal point (about 10cm). #### Sample compression sizes Data | JSON | JSON (gz) | Geobuf | Geobuf (gz) ------------------- | --------: | --------: | -------: | ----------: US zip codes | 101.85 MB | 26.67 MB | 12.24 MB | 10.48 MB Idaho counties | 10.92 MB | 2.57 MB | 1.37 MB | 1.17 MB ## API ### encode ```js const buffer = geobuf.encode(geojson, new Pbf()); ``` Given a GeoJSON object and a [Pbf](https://github.com/mapbox/pbf) object to write to, returns a Geobuf as `UInt8Array` array of bytes. In Node@4.5.0 or later, you can use `Buffer.from` to convert back to a buffer. ### decode ```js const geojson = geobuf.decode(new Pbf(data)); ``` Given a [Pbf](https://github.com/mapbox/pbf) object with Geobuf data, return a GeoJSON object. When loading Geobuf data over `XMLHttpRequest`, you need to set `responseType` to [`arraybuffer`](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/responseType). ## Install ```bash npm install geobuf ``` Browser build CDN links: - https://unpkg.com/geobuf@3.0.2/dist/geobuf.js - https://unpkg.com/geobuf@3.0.2/dist/geobuf-dev.js Building locally: ```bash npm run build ``` ## Command Line ```bash npm install -g geobuf ``` Installs these nifty binaries: * `geobuf2json`: turn Geobuf from `stdin` or specified file to GeoJSON on `stdout` * `json2geobuf`: turn GeoJSON from `stdin` or specified file to Geobuf on `stdout` * `shp2geobuf`: given a Shapefile filename, send Geobuf on `stdout` ```bash json2geobuf data.json > data.pbf shp2geobuf myshapefile > data.pbf geobuf2json data.pbf > data.json ``` Note that for big files, `geobuf2json` command can be pretty slow, but the bottleneck is not the decoding, but the native `JSON.stringify` on the decoded object to pipe it as a string to `stdout`. On some files, this step may take 40 times more time than actual decoding. ## See Also * [geojsonp](https://github.com/springmeyer/geojsonp) — the prototype that led to this project * [pygeobuf](https://github.com/pygeobuf/pygeobuf) — Python implementation of Geobuf * [twkb](https://github.com/TWKB/Specification) — a geospatial binary encoding that doesn't support topology and doesn't encode any non-geographic properties besides `id` * [vector-tile-spec](https://github.com/mapbox/vector-tile-spec) * [topojson](https://github.com/mbostock/topojson) — an extension of GeoJSON that supports topology * [WKT and WKB](https://en.wikipedia.org/wiki/Well-known_text) — popular in databases * [EWKB](http://postgis.refractions.net/docs/using_postgis_dbmanagement.html#EWKB_EWKT) — a popular superset of WKB --- _Source: https://npm.io/package/geobuf · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._