Fast reverse geocoding library with enriched location data. Convert coordinates to detailed place information including timezone, currency, region, and more.

Features

• Simple API - Single function call: genom::lookup(lat, lon)
• Rich Data - Returns 16+ fields including timezone, currency, postal code, region
• Fast Lookups - Grid-based spatial indexing for sub-millisecond queries
• Zero Config - Database builds automatically on first install
• Thread-Safe - Global singleton with lazy initialization
• Compact - Efficient binary format with string interning

Quick Start

use genom;

fn main() {
    // Lookup coordinates
    if let Some(place) = genom::lookup(40.7128, -74.0060) {
        println!("{}, {}", place.city, place.country_name);
        // Output: New York, United States
    }
}

Data enrichment module that adds computed fields to raw geographic data.

This module provides functionality to enrich basic place data with additional information such as:

• Country names from ISO codes
• Currency codes by country
• Continent information
• EU membership status
• Timezone calculations (offset, abbreviation, DST status)

All enrichment data is stored in static lazy-initialized hash maps for efficient lookup.

Core data structures for geographic information.

This module defines the fundamental types used throughout the library:

• Place - Enriched output with complete geographic context
• Location - Simple coordinate pair with distance calculations
• CompactPlace - Compressed storage format using string table indices
• Database - Complete spatial database with grid index

The core geocoding engine. Manages the spatial database and performs coordinate lookups.

Conceptual Role

Geocoder is the transport layer for all geographic queries. It handles:

• Database initialization and decompression
• Grid-based spatial indexing for O(1) lookups
• Nearest-neighbor search across grid cells
• String table resolution for compact storage

What This Type Does NOT Do

• Data enrichment (handled by enrichment module)
• Distance calculations (delegated to Location type)
• Thread synchronization (uses OnceLock for initialization)

Invariants

• After construction, the database is fully loaded and valid
• Grid keys are consistent with coordinate quantization
• String indices in CompactPlace are valid into strings vector

Thread Safety

Geocoder is Send but not Sync. However, the global instance accessed via Geocoder::global() is safe to use from multiple threads because all operations are read-only after initialization.

The enriched output type containing complete geographic context for a location.

This struct is returned by lookup() and contains 18 fields providing comprehensive information about a geographic location.

A coordinate pair with distance calculation capabilities.

This is a simple wrapper around latitude and longitude coordinates that provides utility methods for geographic calculations.

Compressed storage format using string table indices and fixed-point coordinates.

This is the internal storage representation used in the database. All string fields are stored as u32 indices into a shared string table, and coordinates are stored as i32 fixed-point values (multiplied by 100,000).

This reduces memory footprint by approximately 70% compared to storing full Place structs.

The complete spatial database structure with string interning and grid index.

This struct contains all the data needed for geocoding operations. It uses string interning to deduplicate common strings and a spatial grid index for fast coordinate lookups.

The grid divides the world into 0.1° × 0.1° cells. For a lookup:

1. Quantize the input coordinates to a grid key: (lat * 100000 / 10000, lon * 100000 / 10000)
2. Search the target cell and 8 neighboring cells (3×3 grid)
3. Calculate haversine distance to all candidates in these cells
4. Return the nearest place

This provides O(1) average-case lookup with a small constant factor (typically 10-50 candidates to check).

Input structure for the enrich_place function.

This struct contains the basic geographic data that will be enriched with additional computed fields (country name, currency, continent, timezone details, etc.).

Uses borrowed string slices to avoid unnecessary allocations during the enrichment process.

Performs reverse geocoding on the given coordinates, returning enriched place data if found.

Conceptual Role

This is the primary entry point for all geocoding operations. It abstracts away database access, spatial indexing, and data enrichment into a single call.

What This Function Does

• Accesses the global geocoder singleton (lazy initialization on first call)
• Performs grid-based spatial lookup to find nearest place
• Enriches raw data with timezone, currency, and regional information
• Returns None if no place found within search radius

Thread Safety

This function is thread-safe and can be called concurrently from multiple threads. The underlying database is initialized once and shared via a static OnceLock.

Performance

Typical lookup time: <1ms. First call incurs database initialization overhead (~100ms to decompress and load). Subsequent calls are lock-free reads.

Examples

use genom;

// Tokyo coordinates
if let Some(place) = genom::lookup(35.6762, 139.6503) {
    println!("{}, {}", place.city, place.country_name);
    println!("Timezone: {}", place.timezone);
    println!("Currency: {}", place.currency);
}

// Ocean coordinates return None
assert!(genom::lookup(0.0, -160.0).is_none());

Enriches basic place data with computed fields.

This function takes a PlaceInput containing basic geographic information and returns a fully enriched Place with additional computed fields.

Enrichment Process

1. Timezone Parsing: Parses the IANA timezone to extract current offset, abbreviation, and DST status using chrono-tz
2. Country Lookup: Maps country code to full country name using static hash map
3. Currency Lookup: Maps country code to ISO 4217 currency code
4. Continent Lookup: Maps country code to continent code and name
5. EU Status: Checks if country is an EU member state

Static Data Sources

All enrichment data is stored in static LazyLock<FxHashMap> instances:

• COUNTRY_NAMES - 200+ country code to name mappings
• COUNTRY_CURRENCIES - 200+ country code to currency mappings
• COUNTRY_CONTINENTS - 200+ country code to continent mappings
• CONTINENT_NAMES - 7 continent code to name mappings
• EU_COUNTRIES - 27 EU member states

DST Detection

DST status is determined by comparing the current UTC offset with the minimum offset observed in January and July. If the current offset differs from the minimum, DST is active.

Examples

use genom::enrichment::{enrich_place, PlaceInput};

let input = PlaceInput {
    city: "New York",
    region: "New York",
    region_code: "NY",
    district: "New York County",
    country_code: "US",
    postal_code: "10001",
    timezone: "America/New_York",
    latitude: 40.7128,
    longitude: -74.0060,
};

let place = enrich_place(input);
assert_eq!(place.country_name, "United States");
assert_eq!(place.currency, "USD");
assert_eq!(place.continent_name, "North America");
assert_eq!(place.is_eu, false);

Memory Layout

The database uses a highly optimized memory layout:

• String Interning: Common strings stored once, reducing memory by ~60%
• Fixed-Point Coordinates: 32-bit integers instead of 64-bit floats, reducing coordinate storage by 50%
• Spatial Grid: O(1) lookup with small constant factor (10-50 candidates)

Initialization

The database is embedded in the binary at compile time using include_bytes!. On first access:

1. Binary data is decompressed using bincode
2. Database struct is deserialized (~100ms)
3. Reference is stored in static OnceLock
4. All subsequent accesses are instant

Thread Safety

After initialization, all operations are read-only and require no synchronization. Multiple threads can perform lookups concurrently without contention.

Build Process

The database is built from GeoNames data during cargo build:

1. Download GeoNames cities dataset
2. Parse and filter entries
3. Build string table with deduplication
4. Create spatial grid index
5. Serialize to binary format
6. Embed in compiled binary