{"id":45411384,"url":"https://github.com/tn3w/genom","last_synced_at":"2026-06-02T06:00:59.906Z","repository":{"id":337218143,"uuid":"1152739968","full_name":"tn3w/genom","owner":"tn3w","description":"Fast reverse geocoding library with enriched location data.","archived":false,"fork":false,"pushed_at":"2026-05-30T03:54:51.000Z","size":82487,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-05-30T05:20:24.929Z","etag":null,"topics":["geocoding","geolocation","offline","reverse-geocoding","rust","rust-library"],"latest_commit_sha":null,"homepage":"https://genom.tn3w.dev/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tn3w.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"buy_me_a_coffee":"tn3w"}},"created_at":"2026-02-08T11:04:57.000Z","updated_at":"2026-05-24T19:53:49.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tn3w/genom","commit_stats":null,"previous_names":["tn3w/genom"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/tn3w/genom","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tn3w%2Fgenom","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tn3w%2Fgenom/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tn3w%2Fgenom/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tn3w%2Fgenom/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tn3w","download_url":"https://codeload.github.com/tn3w/genom/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tn3w%2Fgenom/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33808702,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-02T02:00:07.132Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["geocoding","geolocation","offline","reverse-geocoding","rust","rust-library"],"created_at":"2026-02-21T23:08:40.116Z","updated_at":"2026-06-02T06:00:59.853Z","avatar_url":"https://github.com/tn3w.png","language":"Rust","funding_links":["https://buymeacoffee.com/tn3w"],"categories":[],"sub_categories":[],"readme":"# genom\n\n[![Crates.io](https://img.shields.io/crates/v/genom.svg)](https://crates.io/crates/genom)\n[![Docs.rs](https://docs.rs/genom/badge.svg)](https://docs.rs/genom)\n[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)\n\nFast offline reverse geocoding with enriched location data.\n\n```\n~37 MB embedded DB\nsub-µs lookup\n18 fields per result\n```\n\n## Install\n\n```toml\n[dependencies]\ngenom = \"2\"\n```\n\n## Use\n\n```rust\nuse genom::lookup;\n\nlet place = lookup(40.7128, -74.0060).unwrap();\nprintln!(\"{}, {}\", place.city, place.country_name); // New York City, United States\nprintln!(\"{} ({})\", place.timezone, place.timezone_abbr); // America/New_York (EDT)\nprintln!(\"{} {}\", place.currency, place.postal_code); // USD 10007\n```\n\nReturns `Option\u003cPlace\u003e` with 18 fields: `city`, `region`, `region_code`,\n`district`, `country_code`, `country_name`, `postal_code`, `timezone`,\n`timezone_abbr`, `utc_offset`, `utc_offset_str`, `latitude`, `longitude`,\n`currency`, `continent_code`, `continent_name`, `is_eu`, `dst_active`.\n\n## How\n\n1. **Compile-time build** (`build.rs`): downloads GeoNames `cities500`,\n   `admin1/2`, `countryInfo`, `allCountries.zip` (postal), and Natural Earth\n   country polygons. Outputs a single compact binary `geo.bin` (~37 MB) into\n   `OUT_DIR`.\n2. **Embedded**: `geo.bin` is `include_bytes!`'d into the final binary.\n3. **Lazy parse**: on first lookup, `Geocoder::global()` parses headers into\n   zero-copy `\u0026'static` slices + two `FxHashMap` indexes (grid → city\n   offset, country → postal section).\n4. **Lookup**: expanding ring search on a 0.1° city grid → nearest city.\n   Refines postal code from a 0.01° per-country grid. Enriches with\n   country/currency/continent/timezone metadata via static maps.\n\nBinary format: varint + zigzag deltas for coords, interned strings, fixed\nsection headers. See `build/builder.rs`.\n\n## CLI\n\n```bash\ncargo build --release\n./target/release/genom 48.8566 2.3522     # reverse-geocode\n./target/release/genom build ./geo.bin    # build the .bin standalone\n./target/release/genom check ./geo.bin    # exit 0 if present, 1 if missing\n```\n\n`build` skips if the file already exists. Raw sources are read from `./data/`\nwhen present, otherwise downloaded into `\u003cout_dir\u003e/genom-cache/`.\n\n## Load from disk\n\nSkip the embedded blob and load a pre-built `geo.bin` at runtime:\n\n```rust\nlet geo = genom::loader::load_from_file(\"geo.bin\")?;\nlet place = geo.lookup(40.7128, -74.0060);\n```\n\nOne syscall, leaked to `\u0026'static [u8]`, pages stay resident → sub-µs lookups.\nSee [`src/loader.rs`](src/loader.rs).\n\n## `genom-golf` self-contained lookup crate\n\n[`golf/`](golf/) is a standalone sibling crate. Single file\n[`golf/src/lib.rs`](golf/src/lib.rs), no `genom` dep, only `chrono` + `chrono-tz`.\nSame `Place` output, byte-identical lookup results.\n\n```rust\nlet geo = genom_golf::Geo::open(\"geo.bin\")?;\nlet place = geo.lookup(40.7128, -74.0060);\n```\n\nOptimized for minimal memory + fast load/lookup:\n\n- Owns `Box\u003c[u8]\u003e` (no leak, no embedded blob).\n- Sorted `Box\u003c[(u32, u32)]\u003e` grid indexes + binary search → no `FxHashMap`,\n  ~3× smaller index than the embedded path.\n- Unaligned `u32` + varint decode on demand; only the two grid arrays cached.\n- Enrichment via sorted `\u0026'static [(u16, CInfo)]` country table, single\n  binary search instead of multiple hashmap probes.\n\n## Build cache\n\n`build.rs` looks for raw GeoNames + Natural Earth downloads in `data/` first,\nthen falls back to network fetch into `OUT_DIR/geonames-cache/`. The repo\nships with `data/` populated so CI builds without network. `data/` is\nexcluded from the published crate via `Cargo.toml`'s `exclude` end users\ninstalling from crates.io download fresh data on first build.\n\n## Skip the build\n\nFor docs.rs / CI without network:\n\n```toml\n[dependencies]\ngenom = { version = \"2\", features = [\"no-build-database\"] }\n```\n\nThe database becomes empty; all lookups return `None`.\n\n## Performance\n\n- **First lookup**: ~5 ms (lazy parse of indexes).\n- **Steady state**: sub-microsecond city scan + postal scan.\n- **Memory**: ~37 MB embedded blob, kept as `\u0026'static [u8]`. Indexes add a\n  few MB of hashmaps.\n\n## Develop\n\n```bash\ncargo build --release\ncargo test --release\ncargo doc --no-deps --open\n```\n\n## Data sources\n\n- [GeoNames.org](https://www.geonames.org/) cities, admin codes, postal CC-BY 4.0\n- [Natural Earth](https://www.naturalearthdata.com/) country polygons public domain\n\n## License\n\nApache-2.0. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftn3w%2Fgenom","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftn3w%2Fgenom","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftn3w%2Fgenom/lists"}