{"id":18230511,"url":"https://github.com/smilyorg/tinygpkg","last_synced_at":"2025-04-03T15:30:28.001Z","repository":{"id":196397728,"uuid":"676285755","full_name":"SmilyOrg/tinygpkg","owner":"SmilyOrg","description":"Go library for local, small, fast reverse geocoding","archived":false,"fork":false,"pushed_at":"2023-12-02T21:04:01.000Z","size":76,"stargazers_count":9,"open_issues_count":0,"forks_count":2,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-19T05:43:23.726Z","etag":null,"topics":["geopackage","geospatial","golang","local","self-hosted","sqlite","twkb","wkb"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SmilyOrg.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2023-08-08T21:24:57.000Z","updated_at":"2024-12-07T14:40:35.000Z","dependencies_parsed_at":null,"dependency_job_id":"5c8b7d75-f0e5-4cde-971e-0e8d1f0f6b4d","html_url":"https://github.com/SmilyOrg/tinygpkg","commit_stats":null,"previous_names":["smilyorg/tinygpkg"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SmilyOrg%2Ftinygpkg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SmilyOrg%2Ftinygpkg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SmilyOrg%2Ftinygpkg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SmilyOrg%2Ftinygpkg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SmilyOrg","download_url":"https://codeload.github.com/SmilyOrg/tinygpkg/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247027643,"owners_count":20871568,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["geopackage","geospatial","golang","local","self-hosted","sqlite","twkb","wkb"],"created_at":"2024-11-04T11:04:25.504Z","updated_at":"2025-04-03T15:30:27.602Z","avatar_url":"https://github.com/SmilyOrg.png","language":"Go","readme":"\u003c!-- HEADER --\u003e\n\u003cbr /\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/SmilyOrg/tinygpkg\"\u003e\n    \u003cimg src=\"assets/logo.png\" alt=\"Logo\" width=\"80\" height=\"80\"\u003e\n  \u003c/a\u003e\n\n  \u003ch3 align=\"center\"\u003etinygpkg\u003c/h3\u003e\n\n  \u003cp align=\"center\"\u003e\n    Go library for local, small, fast reverse geocoding with \u003ca href=\"https://github.com/TWKB/Specification/blob/master/twkb.md\"\u003eTWKB\u003c/a\u003e \u0026 \u003ca href=\"http://www.geopackage.org/\"\u003eGeoPackage\u003c/a\u003e.\n    \u003cbr /\u003e\n    \u003cbr /\u003e\n    \u003ca href=\"https://github.com/SmilyOrg/tinygpkg-data\"\u003e📥 Get Datasets\u003c/a\u003e\n    ·\n    \u003ca href=\"https://github.com/SmilyOrg/tinygpkg/issues\"\u003e🐛 Report Bug\u003c/a\u003e\n    ·\n    \u003ca href=\"https://github.com/SmilyOrg/tinygpkg/issues\"\u003e💡 Request Feature\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/p\u003e\n\n\n\n\u003c!-- TABLE OF CONTENTS --\u003e\n\u003cdetails open=\"open\"\u003e\n  \u003csummary\u003eTable of Contents\u003c/summary\u003e\n  \u003col\u003e\n    \u003cli\u003e\n      \u003ca href=\"#about\"\u003eAbout\u003c/a\u003e\n      \u003cul\u003e\n        \u003cli\u003e\u003ca href=\"#features\"\u003eFeatures\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href=\"#limitations\"\u003eLimitations\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href=\"#built-with\"\u003eBuilt With\u003c/a\u003e\u003c/li\u003e\n      \u003c/ul\u003e\n    \u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#benchmarks\"\u003eBenchmarks\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#usage\"\u003eUsage\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#contributing\"\u003eContributing\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#license\"\u003eLicense\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#acknowledgements\"\u003eAcknowledgements\u003c/a\u003e\u003c/li\u003e\n  \u003c/ol\u003e\n\u003c/details\u003e\n\n\n\n## About\n\ntinygpkg is a Go library for fast, local, and small-scale geospatial processing.\nCurrently the main use-case is local reverse geocoding by using [GeoPackage]\nfiles that have been simplified and compressed into [Tiny Well-known Binary\n(TWKB)] format.\n\nThe library has been heavily inspired by [sams96/rgeo], a Go library for local\nreverse geocoding. The main difference is that `rgeo` uses embedded compressed\nGeoJSON, which it uses to build a [s2.ShapeIndex] at initialization time, while\n`tinygpkg` uses the [GeoPackage] format (based on SQLite), which it queries and\ndeserializes at query time.\n\nThis means that for comparable datasets `tinygpkg` has almost **no startup\ncost** (12ms vs 14s) and **drastically lower runtime memory usage** (27MB vs\n1.5GB) at the expense of **slower reverse geocoding queries** (63µs vs 500ns)\ncompared to `rgeo`. `tinygpkg` can also work with much larger datasets (like\n[geoBoundaries CGAZ]), as it doesn't need to index the entire dataset in memory.\n\n### Features\n\n* **Local** - no network requests needed\n* **Small** - supports [Tiny Well-known Binary (TWKB)] in [GeoPackage] for smaller dataset sizes\n* **Fast** - fast startup time (12ms) and reverse geocoding queries (\u003c1ms)\n* **Low memory usage** - [GeoPackage] files are queried on-the-fly at runtime\n* **Large datasets** - can work with datasets that don't fit in memory\n* **GeoPackage** - uses the [GeoPackage] format reading geospatial data\n* **TWKB** - supports [Tiny Well-known Binary (TWKB)] in GeoPackage for compressed datasets\n\n### Limitations\n\n* **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]\n* **No GeoJSON** - only supports GeoPackage files for now\n\n### Built With\n\n* [Go](https://golang.org/)\n* [GeoPackage](http://www.geopackage.org/) - SQLite-based format for geospatial data\n* [Tiny Well-known Binary (TWKB)] - compressed geometry format\n* [peterstace/simplefeatures](https://github.com/peterstace/simplefeatures) - Go geometry processing library\n* [zombiezen.com/go/sqlite](https://github.com/zombiezen/go-sqlite) - pure Go SQLite library\n\n## Benchmarks\n\nSee a more detailed comparison below using two [Natural Earth] datasets.\n\n[s2.ShapeIndex]: https://pkg.go.dev/github.com/golang/geo/s2#ShapeIndex\n[Natural Earth]: https://www.naturalearthdata.com/\n[geoBoundaries CGAZ]: https://www.geoboundaries.org/downloadCGAZ.html\n\n| Benchmark - [110m countries dataset] | rgeo       | tinygpkg   | % of rgeo |\n| ------------------------------------ | ---------- | ---------- | --------- |\n| Compiled code size                   | **3.2 MB** | 7.8 MB     | 243%      |\n| Bundle size (code + data)            | 32 MB      | **8.2 MB** | 26%       |\n| Startup time                         | 93 ms      | **14 ms**  | 15%       |\n| Startup allocated bytes              | 22 MB      | **12 KB**  | 0.05%     |\n| Runtime memory usage                 | **25 MB**  | 27 MB      | 108%      |\n| Reverse geocode time                 | **1.2 µs** | 87 µs      | 7250%     |\n\n| Benchmark - [10m cities dataset] | rgeo       | tinygpkg    | % of rgeo |\n| -------------------------------- | ---------- | ----------- | --------- |\n| Compiled code size               | **3.2 MB** | 7.8 MB      | 243%      |\n| Bundle size (code + data)        | 32 MB      | **11.5 MB** | 35%       |\n| Bundle size (7z compressed)      | 30 MB      | **5 MB**    | 17%       |\n| Startup time                     | 14000 ms   | **12 ms**   | 0.08%     |\n| Startup allocated bytes          | 6 GB       | **13 KB**   | 0.0002%   |\n| Runtime memory usage             | 1.5 GB     | **27 MB**   | 1.8%      |\n| Reverse geocode time             | **0.5 µs** | 63 µs       | 12600%    |\n\nSee also detailed [benchmark results](/bench/results/).\n\n[110m countries dataset]: https://www.naturalearthdata.com/downloads/110m-cultural-vectors/110m-admin-0-countries/\n[10m cities dataset]: https://www.naturalearthdata.com/downloads/10m-cultural-vectors/10m-urban-area/\n\n\n## Usage\n\n```sh\ngo get github.com/smilyorg/tinygpkg\n```\n\nSee [example](/example), shortened below.\n```go\n\n// Open GeoPackage with dataset and column for reverse geocoding\ng, _ := gpkg.Open(\n  \"../testdata/ne_110m_admin_0_countries_s4_twkb_p3.gpkg\",\n  \"ne_110m_admin_0_countries\",\n  \"NAME\",\n)\ndefer g.Close()\n\n// Reverse geocode a point\np := s2.LatLngFromDegrees(48.8566, 2.3522)\nname, _ := g.ReverseGeocode(context.Background(), p)\nprintln(name)\n\n// Output: France\n```\n\n\n## Contributing\n\nPull requests are welcome. For major changes, please open an issue first to\ndiscuss what you would like to change.\n\n## License\n\nDistributed under the MIT License. See [LICENSE](LICENSE) for more information.\n\n## Acknowledgements\n* [sams96/rgeo] - big inspiration for this library\n* [Best-README-Template](https://github.com/othneildrew/Best-README-Template)\n* [readme.so](https://readme.so/)\n\n[Tiny Well-known Binary (TWKB)]: https://github.com/TWKB/Specification/blob/master/twkb.md\n[GeoPackage]: http://www.geopackage.org/\n[sams96/rgeo]: https://github.com/sams96/rgeo","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmilyorg%2Ftinygpkg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsmilyorg%2Ftinygpkg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmilyorg%2Ftinygpkg/lists"}