offlineRevGeocoder 0.1.0__tar.gz

offlinerevgeocoder-0.1.0/LICENSE

@@ -0,0 +1,26 @@
+MIT License
+
+Copyright (c) 2026 AminJavadi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+Natural Earth data notice:
+The bundled geographic cache is derived from Natural Earth data. Natural Earth
+map data is public domain and may be used, modified, and redistributed. See:
+https://www.naturalearthdata.com/about/terms-of-use/

offlinerevgeocoder-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include README.md
+include LICENSE
+recursive-include offlineRevGeocoder/data *.pkl

offlinerevgeocoder-0.1.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: offlineRevGeocoder
+Version: 0.1.0
+Summary: Fast offline reverse geocoding using a prepared Natural Earth cache
+Home-page: https://github.com/aminjavadi02/reverseGeocoder-py
+Author: AminJavadi
+License: MIT
+Project-URL: Source, https://github.com/aminjavadi02/reverseGeocoder-py
+Project-URL: Natural Earth, https://www.naturalearthdata.com/
+Keywords: geocoder,geocoding,gis,natural-earth,reverse-geocoding
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: GIS
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: requires-python
+Dynamic: summary
+
+# Reverse Geocoder
+
+Tiny offline reverse geocoding for Python.
+
+`offlineRevGeocoder` takes a latitude and longitude and returns a small `GeoResult`
+object with the matching country, continent, ocean, and nearest city when one is
+close enough. It is intentionally simple: the geographic source data is prepared
+ahead of time, cached as a pickle file, and loaded locally at runtime. No API
+keys, no network requests, no external service latency.
+
+The bundled lookup data is derived from [Natural Earth](https://www.naturalearthdata.com/),
+a public domain map dataset. The prepared cache is included so callers can use
+the package immediately.
+
+## Project Info
+
+- PyPI package: `offlineRevGeocoder`
+- Import package: `offlineRevGeocoder`
+- Source code: [github.com/aminjavadi02/reverseGeocoder-py](https://github.com/aminjavadi02/reverseGeocoder-py)
+- License: MIT
+- Author: AminJavadi
+
+This is an open-source package. Bug reports, fixes, data improvements, and
+documentation updates are welcome; please open an issue or send a pull request
+on GitHub.
+
+## Install
+
+```bash
+pip install offlineRevGeocoder
+```
+
+## Usage
+
+```python
+from offlineRevGeocoder import get
+
+result = get(35.6892, 51.3890)
+
+print(result.country)          # Iran
+print(result.country_iso2)     # IR
+print(result.city)             # Tehran
+print(result.precision)        # city
+```
+
+## Common Use Case
+
+This package is most useful when you only need a small reverse geocoding answer,
+for example checking whether a user's latitude and longitude are in or near a
+specific city. In that kind of flow, you often do not need to pay for a full
+reverse geocoding API subscription.
+
+```python
+from offlineRevGeocoder import get
+
+place = get(35.7000, 51.4000, city_radius_km=25)
+
+print(place.city)              # Tehran
+print(place.precision)         # city
+print(place.city == "Tehran")  # True
+```
+
+For a nearby-city check, use `city_radius_km` to control how strict the match
+should be for your product.
+
+## Return Type
+
+`get(lat, lon, city_radius_km=50)` returns:
+
+```python
+GeoResult(
+    continent: str | None,
+    country: str | None,
+    country_iso2: str | None,
+    country_iso3: str | None,
+    ocean: str | None,
+    city: str | None,
+    city_distance_km: float | None,
+    precision: str,
+)
+```
+
+`precision` is one of:
+
+- `city`: a nearby city was found.
+- `country`: the point matched a country, but no nearby city was found.
+- `ocean`: the point matched an ocean or marine area.
+- `none`: no matching land or ocean feature was found.
+
+## Data
+
+The package uses Natural Earth datasets that were transformed into a compact
+pickle cache at `offlineRevGeocoder/data/reverse_geocoder_cache.pkl`. Natural Earth data is
+public domain, so it can be redistributed with this MIT-licensed package.
+
+The code is MIT licensed. Natural Earth requests attribution where possible; this
+README keeps that attribution with the package.

offlinerevgeocoder-0.1.0/README.md

@@ -0,0 +1,97 @@
+# Reverse Geocoder
+
+Tiny offline reverse geocoding for Python.
+
+`offlineRevGeocoder` takes a latitude and longitude and returns a small `GeoResult`
+object with the matching country, continent, ocean, and nearest city when one is
+close enough. It is intentionally simple: the geographic source data is prepared
+ahead of time, cached as a pickle file, and loaded locally at runtime. No API
+keys, no network requests, no external service latency.
+
+The bundled lookup data is derived from [Natural Earth](https://www.naturalearthdata.com/),
+a public domain map dataset. The prepared cache is included so callers can use
+the package immediately.
+
+## Project Info
+
+- PyPI package: `offlineRevGeocoder`
+- Import package: `offlineRevGeocoder`
+- Source code: [github.com/aminjavadi02/reverseGeocoder-py](https://github.com/aminjavadi02/reverseGeocoder-py)
+- License: MIT
+- Author: AminJavadi
+
+This is an open-source package. Bug reports, fixes, data improvements, and
+documentation updates are welcome; please open an issue or send a pull request
+on GitHub.
+
+## Install
+
+```bash
+pip install offlineRevGeocoder
+```
+
+## Usage
+
+```python
+from offlineRevGeocoder import get
+
+result = get(35.6892, 51.3890)
+
+print(result.country)          # Iran
+print(result.country_iso2)     # IR
+print(result.city)             # Tehran
+print(result.precision)        # city
+```
+
+## Common Use Case
+
+This package is most useful when you only need a small reverse geocoding answer,
+for example checking whether a user's latitude and longitude are in or near a
+specific city. In that kind of flow, you often do not need to pay for a full
+reverse geocoding API subscription.
+
+```python
+from offlineRevGeocoder import get
+
+place = get(35.7000, 51.4000, city_radius_km=25)
+
+print(place.city)              # Tehran
+print(place.precision)         # city
+print(place.city == "Tehran")  # True
+```
+
+For a nearby-city check, use `city_radius_km` to control how strict the match
+should be for your product.
+
+## Return Type
+
+`get(lat, lon, city_radius_km=50)` returns:
+
+```python
+GeoResult(
+    continent: str | None,
+    country: str | None,
+    country_iso2: str | None,
+    country_iso3: str | None,
+    ocean: str | None,
+    city: str | None,
+    city_distance_km: float | None,
+    precision: str,
+)
+```
+
+`precision` is one of:
+
+- `city`: a nearby city was found.
+- `country`: the point matched a country, but no nearby city was found.
+- `ocean`: the point matched an ocean or marine area.
+- `none`: no matching land or ocean feature was found.
+
+## Data
+
+The package uses Natural Earth datasets that were transformed into a compact
+pickle cache at `offlineRevGeocoder/data/reverse_geocoder_cache.pkl`. Natural Earth data is
+public domain, so it can be redistributed with this MIT-licensed package.
+
+The code is MIT licensed. Natural Earth requests attribution where possible; this
+README keeps that attribution with the package.

offlinerevgeocoder-0.1.0/offlineRevGeocoder/__init__.py

@@ -0,0 +1,3 @@
+from .reverseGeocoder import GeoResult, get
+
+__all__ = ["GeoResult", "get"]

offlinerevgeocoder-0.1.0/offlineRevGeocoder/reverseGeocoder.py

@@ -0,0 +1,150 @@
+from __future__ import annotations
+
+import math
+import pickle
+from dataclasses import dataclass
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+CACHE = Path(__file__).resolve().parent / "data" / "reverse_geocoder_cache.pkl"
+CACHE_VERSION = 3
+EARTH_RADIUS_KM = 6371.0088
+
+
+@dataclass(frozen=True, slots=True)
+class GeoResult:
+    continent: str | None
+    country: str | None
+    country_iso2: str | None
+    country_iso3: str | None
+    ocean: str | None
+    city: str | None
+    city_distance_km: float | None
+    precision: str
+
+
+C_CONTINENT, C_COUNTRY, C_ISO2, C_ISO3, C_BBOX, C_RINGS = range(6)
+CITY_NAME, CITY_ISO2, CITY_LAT, CITY_LON = range(4)
+M_NAME, M_BBOX, M_RINGS = range(3)
+
+
+def get(lat: float, lon: float, *, city_radius_km: float = 50) -> GeoResult:
+    _validate(lat, lon)
+    data = _load()
+    country = _find_country(data, lat, lon)
+    ocean = None if country else _find_ocean(data, lat, lon)
+    city = _find_city(data, lat, lon, city_radius_km, country)
+    return GeoResult(
+        continent=country[C_CONTINENT] if country else None,
+        country=country[C_COUNTRY] if country else None,
+        country_iso2=country[C_ISO2] if country else None,
+        country_iso3=country[C_ISO3] if country else None,
+        ocean=ocean[M_NAME] if ocean else None,
+        city=city[0][CITY_NAME] if city else None,
+        city_distance_km=round(city[1], 3) if city else None,
+        precision="city" if city else "country" if country else "ocean" if ocean else "none",
+    )
+
+
+@lru_cache(maxsize=1)
+def _load() -> dict[str, Any]:
+    if not CACHE.exists():
+        raise RuntimeError("missing reverse geocoder cache; run python3 prepare.py")
+    with CACHE.open("rb") as f:
+        data = pickle.load(f)
+    if data.get("version") != CACHE_VERSION:
+        raise RuntimeError("stale reverse geocoder cache; run python3 prepare.py")
+    return data
+
+
+def _find_country(data: dict[str, Any], lat: float, lon: float) -> tuple[Any, ...] | None:
+    cell = _cell_id(*_cell(lat, lon, data["country_cell"]), data["country_grid_width"])
+    for i in data["country_grid"].get(cell, []):
+        country = data["countries"][i]
+        if _in_bbox(lat, lon, country[C_BBOX]) and _in_polygon(lat, lon, country[C_RINGS]):
+            return country
+    return None
+
+
+def _find_ocean(data: dict[str, Any], lat: float, lon: float) -> tuple[Any, ...] | None:
+    cell = _cell_id(*_cell(lat, lon, data["marine_cell"]), data["marine_grid_width"])
+    for i in data["marine_grid"].get(cell, []):
+        ocean = data["marine"][i]
+        if _in_bbox(lat, lon, ocean[M_BBOX]) and _in_polygon(lat, lon, ocean[M_RINGS]):
+            return ocean
+    return None
+
+
+def _find_city(data: dict[str, Any], lat: float, lon: float, radius_km: float, country: tuple[Any, ...] | None) -> tuple[tuple[Any, ...], float] | None:
+    size = data["city_cell"]
+    radius_cells = max(1, math.ceil((radius_km / 111.0) / size))
+    width = data["city_grid_width"]
+    cx, cy = _cell(lat, lon, size)
+    best_city = None
+    best_distance = radius_km
+    country_iso2 = country[C_ISO2] if country else None
+    for x in range(cx - radius_cells, cx + radius_cells + 1):
+        for y in range(cy - radius_cells, cy + radius_cells + 1):
+            for i in data["city_grid"].get(_cell_id(x, y, width), []):
+                city = data["cities"][i]
+                if country_iso2 and city[CITY_ISO2] and city[CITY_ISO2] != country_iso2:
+                    continue
+                distance = _haversine(lat, lon, city[CITY_LAT], city[CITY_LON])
+                if distance <= best_distance:
+                    best_city = city
+                    best_distance = distance
+    return (best_city, best_distance) if best_city else None
+
+
+def _in_polygon(lat: float, lon: float, rings: list[tuple]) -> bool:
+    inside = False
+    for bbox, points in rings:
+        if _in_bbox(lat, lon, bbox) and _point_in_ring(lat, lon, points):
+            inside = not inside
+    return inside
+
+
+def _point_in_ring(lat: float, lon: float, ring: list[tuple[float, float]]) -> bool:
+    inside = False
+    j = len(ring) - 1
+    for i, (xi, yi) in enumerate(ring):
+        xj, yj = ring[j]
+        if ((xi <= lon <= xj) or (xj <= lon <= xi)) and ((yi <= lat <= yj) or (yj <= lat <= yi)):
+            cross = (lat - yi) * (xj - xi) - (lon - xi) * (yj - yi)
+            if abs(cross) <= 1e-10:
+                return True
+        if (yi > lat) != (yj > lat):
+            x_at_lat = (xj - xi) * (lat - yi) / (yj - yi) + xi
+            if lon < x_at_lat:
+                inside = not inside
+        j = i
+    return inside
+
+
+def _in_bbox(lat: float, lon: float, bbox: tuple[float, float, float, float]) -> bool:
+    minx, miny, maxx, maxy = bbox
+    return minx <= lon <= maxx and miny <= lat <= maxy
+
+
+def _haversine(lat1: float, lon1: float, lat2: float, lon2: float) -> float:
+    p1, p2 = math.radians(lat1), math.radians(lat2)
+    dp = math.radians(lat2 - lat1)
+    dl = math.radians(lon2 - lon1)
+    a = math.sin(dp / 2) ** 2 + math.cos(p1) * math.cos(p2) * math.sin(dl / 2) ** 2
+    return 2 * EARTH_RADIUS_KM * math.atan2(math.sqrt(a), math.sqrt(1 - a))
+
+
+def _cell(lat: float, lon: float, size: float) -> tuple[int, int]:
+    return math.floor((lon + 180.0) / size), math.floor((lat + 90.0) / size)
+
+
+def _cell_id(x: int, y: int, width: int) -> int:
+    return y * width + x
+
+
+def _validate(lat: float, lon: float) -> None:
+    if not -90 <= lat <= 90:
+        raise ValueError("lat must be between -90 and 90")
+    if not -180 <= lon <= 180:
+        raise ValueError("lon must be between -180 and 180")

offlinerevgeocoder-0.1.0/offlineRevGeocoder.egg-info/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: offlineRevGeocoder
+Version: 0.1.0
+Summary: Fast offline reverse geocoding using a prepared Natural Earth cache
+Home-page: https://github.com/aminjavadi02/reverseGeocoder-py
+Author: AminJavadi
+License: MIT
+Project-URL: Source, https://github.com/aminjavadi02/reverseGeocoder-py
+Project-URL: Natural Earth, https://www.naturalearthdata.com/
+Keywords: geocoder,geocoding,gis,natural-earth,reverse-geocoding
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: GIS
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: requires-python
+Dynamic: summary
+
+# Reverse Geocoder
+
+Tiny offline reverse geocoding for Python.
+
+`offlineRevGeocoder` takes a latitude and longitude and returns a small `GeoResult`
+object with the matching country, continent, ocean, and nearest city when one is
+close enough. It is intentionally simple: the geographic source data is prepared
+ahead of time, cached as a pickle file, and loaded locally at runtime. No API
+keys, no network requests, no external service latency.
+
+The bundled lookup data is derived from [Natural Earth](https://www.naturalearthdata.com/),
+a public domain map dataset. The prepared cache is included so callers can use
+the package immediately.
+
+## Project Info
+
+- PyPI package: `offlineRevGeocoder`
+- Import package: `offlineRevGeocoder`
+- Source code: [github.com/aminjavadi02/reverseGeocoder-py](https://github.com/aminjavadi02/reverseGeocoder-py)
+- License: MIT
+- Author: AminJavadi
+
+This is an open-source package. Bug reports, fixes, data improvements, and
+documentation updates are welcome; please open an issue or send a pull request
+on GitHub.
+
+## Install
+
+```bash
+pip install offlineRevGeocoder
+```
+
+## Usage
+
+```python
+from offlineRevGeocoder import get
+
+result = get(35.6892, 51.3890)
+
+print(result.country)          # Iran
+print(result.country_iso2)     # IR
+print(result.city)             # Tehran
+print(result.precision)        # city
+```
+
+## Common Use Case
+
+This package is most useful when you only need a small reverse geocoding answer,
+for example checking whether a user's latitude and longitude are in or near a
+specific city. In that kind of flow, you often do not need to pay for a full
+reverse geocoding API subscription.
+
+```python
+from offlineRevGeocoder import get
+
+place = get(35.7000, 51.4000, city_radius_km=25)
+
+print(place.city)              # Tehran
+print(place.precision)         # city
+print(place.city == "Tehran")  # True
+```
+
+For a nearby-city check, use `city_radius_km` to control how strict the match
+should be for your product.
+
+## Return Type
+
+`get(lat, lon, city_radius_km=50)` returns:
+
+```python
+GeoResult(
+    continent: str | None,
+    country: str | None,
+    country_iso2: str | None,
+    country_iso3: str | None,
+    ocean: str | None,
+    city: str | None,
+    city_distance_km: float | None,
+    precision: str,
+)
+```
+
+`precision` is one of:
+
+- `city`: a nearby city was found.
+- `country`: the point matched a country, but no nearby city was found.
+- `ocean`: the point matched an ocean or marine area.
+- `none`: no matching land or ocean feature was found.
+
+## Data
+
+The package uses Natural Earth datasets that were transformed into a compact
+pickle cache at `offlineRevGeocoder/data/reverse_geocoder_cache.pkl`. Natural Earth data is
+public domain, so it can be redistributed with this MIT-licensed package.
+
+The code is MIT licensed. Natural Earth requests attribution where possible; this
+README keeps that attribution with the package.

offlinerevgeocoder-0.1.0/offlineRevGeocoder.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+MANIFEST.in
+README.md
+setup.py
+offlineRevGeocoder/__init__.py
+offlineRevGeocoder/reverseGeocoder.py
+offlineRevGeocoder.egg-info/PKG-INFO
+offlineRevGeocoder.egg-info/SOURCES.txt
+offlineRevGeocoder.egg-info/dependency_links.txt
+offlineRevGeocoder.egg-info/top_level.txt
+offlineRevGeocoder/data/__init__.py
+offlineRevGeocoder/data/reverse_geocoder_cache.pkl

offlinerevgeocoder-0.1.0/offlineRevGeocoder.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

offlinerevgeocoder-0.1.0/offlineRevGeocoder.egg-info/top_level.txt

@@ -0,0 +1 @@
+offlineRevGeocoder

offlinerevgeocoder-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

offlinerevgeocoder-0.1.0/setup.py

@@ -0,0 +1,39 @@
+from pathlib import Path
+
+from setuptools import setup
+
+ROOT = Path(__file__).parent
+README = (ROOT / "README.md").read_text(encoding="utf-8")
+
+setup(
+    name="offlineRevGeocoder",
+    version="0.1.0",
+    description="Fast offline reverse geocoding using a prepared Natural Earth cache",
+    long_description=README,
+    long_description_content_type="text/markdown",
+    author="AminJavadi",
+    url="https://github.com/aminjavadi02/reverseGeocoder-py",
+    project_urls={
+        "Source": "https://github.com/aminjavadi02/reverseGeocoder-py",
+        "Natural Earth": "https://www.naturalearthdata.com/",
+    },
+    packages=["offlineRevGeocoder", "offlineRevGeocoder.data"],
+    include_package_data=True,
+    package_data={"offlineRevGeocoder": ["data/*.pkl"]},
+    python_requires=">=3.10",
+    install_requires=[],
+    license="MIT",
+    license_files=["LICENSE"],
+    classifiers=[
+        "Development Status :: 3 - Alpha",
+        "Intended Audience :: Developers",
+        "License :: OSI Approved :: MIT License",
+        "Operating System :: OS Independent",
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
+        "Programming Language :: Python :: 3.12",
+        "Topic :: Scientific/Engineering :: GIS",
+    ],
+    keywords=["geocoder", "geocoding", "gis", "natural-earth", "reverse-geocoding"],
+)