Metadata-Version: 2.4
Name: osm-simplify
Version: 1.1.0
Summary: Lightweight, zero-dependency offline PBF spatial grid index and OSM search library.
Author: Dogu Hatipoglu
License: MIT
Project-URL: Homepage, https://github.com/DoguH72/osm-simplify
Project-URL: Repository, https://github.com/DoguH72/osm-simplify
Project-URL: Bug Tracker, https://github.com/DoguH72/osm-simplify/issues
Keywords: openstreetmap,overpass-api,gis,nominatim,geocoding,spatial-search,osm
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests
Dynamic: license-file

# 🌍 osm-simplify

`osm-simplify` is a lightweight, dependency-minimal Python library designed to make querying OpenStreetMap (OSM) data effortless. Whether you are building local search features, geographic data parsers, or offline mapping applications, this library bridges the gap between raw map data and clean, ready-to-use Python objects.

---

## 💡 Why Use `osm-simplify`? (The Benefits)

Working directly with OpenStreetMap's Overpass API or raw `.osm` XML files can be tedious, requiring complex query syntax and error-prone XML parsing. `osm-simplify` solves this by giving you:

- **Zero Heavy GIS Bloat:** Avoid installing massive, hard-to-configure geographic libraries like `GDAL` or `GeoPandas` just to find nearby places.
- **Smart Dual-Mode Engine:** Query live public Overpass servers with built-in failover, or seamlessly switch to parsing local `.osm` XML files offline when you're without internet or testing locally.
- **Automatic Tag Expansion:** You don't need to write complex Overpass QL syntax. Simple presets (like `Category.FOOD` or `Category.PARK`) automatically expand behind the scenes to capture relevant nodes, ways, and boundaries.
- **Instant Distance Sorting:** Search results are instantly cleaned up, converted into structured `Place` data classes, and sorted by physical distance from your target location.
- **Built-in Memory Caching:** Remembers recent queries to ensure fast repeat lookups without spamming public servers.

---

## 🚀 Installation & Local Clone

You can install the package directly from PyPI:

pip install osm-simplify

Or if you want to perform a local clone for development:

git clone https://github.com/DoguH72/osm-simplify.git
cd osm-simplify
pip install -e .

---

## 📖 Quick Start

Here is how simple it is to find nearby restaurants or historical monuments around a location:

import os
from osm_simplify import GeoFinder, Category

# 1. Initialize your search anchor (via address or direct coordinates)
spot = GeoFinder.from_address("Piazza Castello", "Turin")

# (Optional) Attach a local .osm XML file for offline fallback
if os.path.exists("sample_lib.osm"):
    spot.local_file = "sample_lib.osm"

# 2. Find nearby food spots within 500 meters (automatically sorted by distance!)
restaurants = spot.get_nearby(Category.FOOD, radius_m=500)

for place in restaurants:
    print(f"- {place.name} ({place.subtype}): {place.distance_m}m away")

# 3. Find the single closest monument
closest = spot.get_closest(Category.MONUMENT, radius_m=1000)
if closest:
    print(f"Closest Monument: {closest.name} @ {closest.distance_m}m")

---

## 🛠️ Custom Change (Custom Categories)

Need something specific that isn't in the default presets? You can define custom search filters on the fly:

CUSTOM_CAFE_FILTER = {
    "name": "cafes",
    "overpass": ('["amenity"="cafe"]',)
}

cafes = spot.get_nearby(CUSTOM_CAFE_FILTER, radius_m=600)

---

## 🧩 Core API Reference

- **`GeoFinder`**: The core spatial engine handling online API requests, failovers, and offline XML traversal.
- **`Place`**: A clean dataclass representing a location point (`.name`, `.category`, `.subtype`, `.lat`, `.lon`, `.distance_m`, `.to_dict()`).
- **`Category`**: Pre-configured presets (`Category.FOOD`, `Category.PARK`, `Category.MONUMENT`, etc.).
- **`OverpassServerError`**: Custom exception raised when public mapping mirrors are overloaded.

---

## 📄 License

Distributed under the **MIT License**. Feel free to use, modify, and adapt it for your own projects!
