smilyorg / tinygpkg Goto Github PK

Go library for local, small, fast reverse geocoding with TWKB & GeoPackage.

📥 Get Datasets · 🐛 Report Bug · 💡 Request Feature

tinygpkg is a Go library for fast, local, and small-scale geospatial processing. Currently the main use-case is local reverse geocoding by using GeoPackage files that have been simplified and compressed into Tiny Well-known Binary (TWKB) format.

The library has been heavily inspired by sams96/rgeo, a Go library for local reverse geocoding. The main difference is that rgeo uses embedded compressed GeoJSON, which it uses to build a s2.ShapeIndex at initialization time, while tinygpkg uses the GeoPackage format (based on SQLite), which it queries and deserializes at query time.

This means that for comparable datasets tinygpkg has almost no startup cost (12ms vs 14s) and drastically lower runtime memory usage (27MB vs 1.5GB) at the expense of slower reverse geocoding queries (63µs vs 500ns) compared to rgeo. tinygpkg can also work with much larger datasets (like geoBoundaries CGAZ), as it doesn't need to index the entire dataset in memory.

• Local - no network requests needed
• Small - supports Tiny Well-known Binary (TWKB) in GeoPackage for smaller dataset sizes
• Fast - fast startup time (12ms) and reverse geocoding queries (<1ms)
• Low memory usage - GeoPackage files are queried on-the-fly at runtime
• Large datasets - can work with datasets that don't fit in memory
• GeoPackage - uses the GeoPackage format reading geospatial data
• TWKB - supports Tiny Well-known Binary (TWKB) in GeoPackage for compressed datasets

• Slower queries - each query needs to do a database lookup, geometry deserialization, and point-in-polygon check - it's still plenty fast (microseconds), but not as fast as sams96/rgeo that uses s2.ShapeIndex
• No GeoJSON - only supports GeoPackage files for now

• Go
• GeoPackage - SQLite-based format for geospatial data
• Tiny Well-known Binary (TWKB) - compressed geometry format
• peterstace/simplefeatures - Go geometry processing library
• zombiezen.com/go/sqlite - pure Go SQLite library

See a more detailed comparison below using two Natural Earth datasets.

See also detailed benchmark results.

go get github.com/smilyorg/tinygpkg

See example, shortened below.

// Open GeoPackage with dataset and column for reverse geocoding
g, _ := gpkg.Open(
  "../testdata/ne_110m_admin_0_countries_s4_twkb_p3.gpkg",
  "ne_110m_admin_0_countries",
  "NAME",
)
defer g.Close()

// Reverse geocode a point
p := s2.LatLngFromDegrees(48.8566, 2.3522)
name, _ := g.ReverseGeocode(context.Background(), p)
println(name)

// Output: France

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Distributed under the MIT License. See LICENSE for more information.

• sams96/rgeo - big inspiration for this library
• Best-README-Template
• readme.so