Metadata-Version: 2.4
Name: osmdb
Version: 0.1.1
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Rust
Classifier: Typing :: Typed
Requires-Dist: maturin>=1.9.4,<2 ; extra == 'dev'
Requires-Dist: mypy>=1.15 ; extra == 'dev'
Requires-Dist: pytest>=8 ; extra == 'dev'
Provides-Extra: dev
License-File: LICENSE
Summary: Strongly typed Python bindings for querying osmdb databases
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# osmdb

`osmdb` imports OpenStreetMap PBF files into a local database and provides fast, read-only access from a CLI, Rust, or Python.

Import a PBF once, then query locations, tagged nodes, ways, and relations by their OSM IDs. Node coordinates are stored in a memory-mapped file for O(1) lookups; the remaining entities are stored in RocksDB.

## CLI

The CLI requires Rust 1.85 or newer, a C/C++ build toolchain, and libclang.

```bash
cargo install osmdb
osmdb import --pbf world.osm.pbf --output ./world-db
```

The output directory must be new. Once the import completes, look up one or more IDs:

```bash
osmdb lookup --db ./world-db location 240109189
osmdb lookup --db ./world-db node 123456789
osmdb lookup --db ./world-db way 12345678 87654321
osmdb lookup --db ./world-db relation 123456
```

See [CLI usage](docs/cli.md) for prerequisites, aliases, and command details.

## Rust

```toml
[dependencies]
osmdb = "0.1.0"
```

```rust
use osmdb::DatabaseReader;

let reader = DatabaseReader::open("world-db")?;

let location = reader.get_location(240109189)?;
let node = reader.get_node(123456789)?;
let way = reader.get_way(12345678)?;
let relation = reader.get_relation(123456)?;
```

Each lookup returns `Ok(Some(entity))` when the ID exists and `Ok(None)` when it does not. See the [Rust guide](docs/rust.md) for geometry and iteration.

## Python

The typed Python package requires CPython 3.10 or newer and reads databases created by the CLI.

```bash
pip install osmdb
```

```python
from osmdb import Database

with Database("world-db") as db:
    location = db.get_location(240109189)
    way = db.get_way(12345678)

    if way is not None:
        coordinates = db.get_way_geometry(way)
```

See the [Python guide](docs/python.md) for typed entities, iterators, and source builds.

## Documentation

- [CLI usage](docs/cli.md)
- [Rust API](docs/rust.md)
- [Python API](docs/python.md)
- [Storage format](docs/storage.md)
- [Development](docs/development.md)

Licensed under the [Apache License 2.0](LICENSE).

