geodb-rs

A high-performance, pure-Rust geographic database with countries, states/regions, cities, aliases, phone codes, currencies, timezones, and WebAssembly support.

This repository is a Cargo workspace containing:

• geodb-core — main geographic database library (published on crates.io)
• geodb-wasm — WebAssembly bindings + browser demo (Trunk-based)
• geodb-cli — optional CLI (future)

Overview

geodb-core provides:

• 🚀 Fast loading from compressed JSON or binary cache
• 💾 Automatic caching based on dataset file and filters
• 🔎 Flexible lookups: ISO codes, names, aliases, phone codes
• 🌍 Countries, states/regions, cities, populations
• 🗺 Accurate metadata: region, subregion, currency
• 📞 Phone code search
• ⏱ Zero-copy internal model
• 🦀 Pure Rust — no unsafe
• 🕸 WASM support via geodb-wasm

The dataset is adapted from
https://github.com/dr5hn/countries-states-cities-database
(licensed under CC-BY-4.0, attribution required).

Important: Data source we rely on

geodb-core ships and expects the upstream dataset from the following file in the dr5hn/countries-states-cities-database repository:

https://github.com/dr5hn/countries-states-cities-database/blob/master/json/countries%2Bstates%2Bcities.json.gz

The default loader uses a copy of this file placed under crates/geodb-core/data/countries+states+cities.json.gz and builds a binary cache alongside it. If you update or replace the dataset, ensure it retains the same JSON structure. Please observe the CC‑BY‑4.0 license and attribution of the upstream project.

Installation

For Rust applications

[dependencies]
geodb-core = "0.2"

For WebAssembly (browser/Node)

[dependencies]
geodb-wasm = "0.2"

Quick Start

use geodb_core::prelude::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let db = GeoDb::<StandardBackend>::load()?;

    if let Some(country) = db.find_country_by_iso2("US") {
        println!("Country: {}", country.name());
        println!("Capital: {:?}", country.capital());
        println!("Phone Code: {}", country.phone_code());
        println!("Currency: {}", country.currency());
    }

    Ok(())
}

Loading & Caching

Default loading

Loads from:

geodb-core/data/countries+states+cities.json.gz

Creates automatic cache:

countries+states+cities.json.ALL.bin

let db = GeoDb::<StandardBackend>::load()?;

Load from a custom file

let db = GeoDb::<StandardBackend>::load_from_path(
    "path/to/worlddata.json.gz",
    None,
)?;

Cache becomes:

worlddata.json.ALL.bin

Filtered loading (ISO2)

let db = GeoDb::<StandardBackend>::load_filtered_by_iso2(&["DE", "US"])?;

Cache:

countries+states+cities.json.DE_US.bin

Cache rules:

<dataset_filename>.<filter>.bin

Usage Examples

List all countries

use geodb_core::prelude::*;

let db = GeoDb::<StandardBackend>::load()?;
for country in db.countries() {
    println!("{} ({})", country.name(), country.iso2());
}

Find by ISO code

if let Some(country) = db.find_country_by_iso2("DE") {
    println!("Found {}", country.name());
}

Country details

if let Some(fr) = db.find_country_by_iso2("FR") {
    println!("Capital: {:?}", fr.capital());
    println!("Currency: {}", fr.currency());
    println!("Region: {}", fr.region());
}

States & cities

if let Some(us) = db.find_country_by_iso2("US") {
    let states = us.states();
    if let Some(ca) = states.iter().find(|s| s.state_code() == "CA") {
        for city in ca.cities() {
            println!("{}", city.name());
        }
    }
}

Phone search

let countries = db.find_countries_by_phone_code("+44");

Search for cities named “Springfield”

let results: Vec<_> = db.countries()
    .iter()
    .flat_map(|country| {
        country.states().iter().flat_map(move |state| {
            state.cities().iter()
                .filter(|c| c.name() == "Springfield")
                .map(move |c| (country.name(), state.name(), c.name()))
        })
    })
    .collect();

WebAssembly (geodb-wasm)

Exports:

• search_country_prefix
• search_countries_by_phone
• search_state_substring
• search_city_substring
• smart_search
• get_stats

To run locally:

cd crates/geodb-wasm
cargo install trunk
trunk serve

Live demo:
https://trahe.eu/geodb-rs.html

Workspace Layout

geodb-rs/
├── crates/
│   ├── geodb-core
│   ├── geodb-wasm
│   └── geodb-cli (planned)
├── data/
│   ├── countries+states+cities.json.gz
│   └── geodb.standard.bin
├── examples/
├── scripts/
└── README.md

Performance

• Initial load from JSON: ~20–40ms
• Cached load: ~1–3ms
• Memory use: 10–15MB
• Fully zero-copy internal model

Contributing

Before submitting PRs:

cargo fmt
cargo clippy --all-targets -- -D warnings
cargo test --workspace
cargo doc --workspace
cargo sort -cwg
taplo format --check
cargo deny check

License

Code

MIT License.

Data Attribution (Required)

This project includes data from:

countries-states-cities-database
https://github.com/dr5hn/countries-states-cities-database
Licensed under Creative Commons Attribution 4.0 (CC-BY-4.0).
Attribution is required if you redistribute or use the dataset.

Links

• Repo: https://github.com/holg/geodb-rs
• Docs: https://docs.rs/geodb-core
• Crate: https://crates.io/crates/geodb-core

Made with ❤️ in Rust.