wilayah 0.5.1

Location lookup for Indonesian villages by GPS coordinates or name
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109

//! Location lookup for Indonesian villages by GPS coordinates or name.
//!
//! Returns BMKG-compatible `adm4` administrative codes (e.g., `31.71.03.1001`)
//! for 82,689 villages across Indonesia, based on official Kemendagri
//! administrative codes with pre-computed village centroids from BIG (Badan
//! Informasi Geospasial) polygon boundaries.
//!
//! # Quick start
//!
//! ```
//! use wilayah::Database;
//!
//! let db = Database::open().expect("database");
//! let nearest = db.find_nearest(-6.1647, 106.8453, 5).expect("query");
//! assert!(!nearest.is_empty());
//! ```
//!
//! # Data
//!
//! Sourced from the official Kemendagri (Ministry of Home Affairs) PDF
//! publication of all Indonesian villages, combined with village polygon
//! boundaries from BIG (Badan Informasi Geospasial) ArcGIS service. The data is
//! processed through a reproducible build pipeline to produce a SQLite database
//! with RTree spatial index and FTS5 full-text search. The database is embedded
//! into the binary at compile time via a build script.
//!
//! On first `cargo build`, the build script downloads a pre-built database
//! from the GitHub Releases. Subsequent builds reuse the cached database
//! located at `data/locations.db`.
//!
//! To build from scratch, run:
//!
//! ```bash
//! cargo run --example build_db --features build-db
//! ```
//!
//! # Feature flags
//!
//! - **`db`** *(enabled by default)* — Embedded SQLite database via `rusqlite`.
//!   Enables [`Database`], [`Error`], and all query methods.
//! - **`build-db`** — Pipeline for building the database from source data.
//! - **`types`** — *(always available)* Shared types ([`Village`], [`Location`],
//!   [`AdminLevel`], [`LocateMethod`]) and [`haversine_km()`]. Use this with
//!   `default-features = false` when you only need the types (e.g., Cloudflare
//!   Workers with a different database backend).
//! - **`raw-sqlite`** — Exposes `Database::conn_guard()` for direct `rusqlite`
//!   access. Using this accessor makes your code dependent on `rusqlite`'s API.

#![deny(missing_docs)]

/// Shared types and utilities for Indonesian village location data.
///
/// This module is always available regardless of feature flags. It contains
/// the core data types ([`Village`], [`Location`], [`AdminLevel`], etc.),
/// the [`haversine_km`] distance function, and the [`location_from_village`]
/// helper for building administrative hierarchies from village codes.
pub mod types;

/// Point-in-polygon algorithms and vertex serialization.
///
/// Contains [`PipResult`], [`point_in_ring`], [`point_in_polygon`],
/// [`bbox`], [`serialize_vertices`], and [`deserialize_vertices`].
/// These are also re-exported from [`types`] for backward compatibility.
pub mod geometry;

#[cfg(feature = "db")]
mod db;

#[cfg(feature = "build-db")]
pub mod builder;

pub use types::{
    bbox, deserialize_vertices, haversine_km, location_from_village, point_in_polygon,
    point_in_ring, serialize_vertices, AdminLevel, DataInfo, LocateMethod, Location, LookupResult,
    PipResult, PrefixResult, Village, CODE_PREFIX_MAX_LIMIT, NEAREST_MAX_LIMIT, SEARCH_MAX_LIMIT,
};

#[cfg(feature = "build-db")]
pub use builder::RingClassification;

#[cfg(feature = "db")]
pub use db::{Database, Error};

/// Get the version of this crate.
///
/// Returns the `Cargo.toml` version string.
pub const fn version() -> &'static str {
    env!("CARGO_PKG_VERSION")
}

/// Get metadata about the embedded location database.
///
/// Returns source, decree, village count, and build timestamp information
/// stored in the `db_meta` table of the embedded database. The result is
/// cached after the first call.
///
/// # Example
///
/// ```
/// let info = wilayah::data_info();
/// // village_count and build_date are 0 if the DB predates the db_meta table
/// if info.village_count > 0 {
///     assert!(info.village_count > 80000);
/// }
/// ```
#[cfg(feature = "db")]
pub fn data_info() -> DataInfo {
    db::cached_data_info().clone()
}