chile-reverse-geocoder 0.1.0__py3-none-any.whl

chile_reverse_geocoder/__init__.py

@@ -0,0 +1,7 @@
+"""chile-reverse-geocoder: Offline administrative reverse geocoding for Chile."""
+
+from .exceptions import InvalidCoordinatesError, InvalidLevelError
+from .geocoder import lookup
+
+__all__ = ["lookup", "InvalidCoordinatesError", "InvalidLevelError"]
+__version__ = "0.1.0"

chile_reverse_geocoder/exceptions.py

@@ -0,0 +1,6 @@
+class InvalidCoordinatesError(ValueError):
+    """Raised when lat/lon values are outside valid geographic ranges or are not finite numbers."""
+
+
+class InvalidLevelError(ValueError):
+    """Raised when the 'level' argument is not one of: None, 'region', 'province', 'commune'."""

chile_reverse_geocoder/geocoder.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+import math
+
+import shapely
+
+from .exceptions import InvalidCoordinatesError, InvalidLevelError
+from .loader import GeocoderData, load_data
+
+_VALID_LEVELS = frozenset({"region", "province", "commune"})
+
+_cache: GeocoderData | None = None
+
+
+def _get_data() -> GeocoderData:
+    global _cache
+    if _cache is None:
+        _cache = load_data()
+    return _cache
+
+
+def _validate_coordinates(lat: float, lon: float) -> None:
+    if not isinstance(lat, (int, float)) or not isinstance(lon, (int, float)):
+        raise InvalidCoordinatesError(
+            f"lat and lon must be numeric, got {type(lat).__name__}, {type(lon).__name__}"
+        )
+    if math.isnan(lat) or math.isnan(lon) or math.isinf(lat) or math.isinf(lon):
+        raise InvalidCoordinatesError(
+            f"lat and lon must be finite numbers, got lat={lat}, lon={lon}"
+        )
+    if not (-90.0 <= lat <= 90.0):
+        raise InvalidCoordinatesError(f"lat must be in [-90, 90], got {lat}")
+    if not (-180.0 <= lon <= 180.0):
+        raise InvalidCoordinatesError(f"lon must be in [-180, 180], got {lon}")
+
+
+def lookup(lat: float, lon: float, level: str | None = None) -> dict | None:
+    """Return administrative divisions for the given coordinates.
+
+    Args:
+        lat: Latitude in decimal degrees (WGS84).
+        lon: Longitude in decimal degrees (WGS84).
+        level: One of 'region', 'province', 'commune', or None for all levels.
+
+    Returns:
+        Dict with administrative division(s), or None if outside Chile.
+
+    Raises:
+        InvalidCoordinatesError: If lat/lon are not valid geographic coordinates.
+        InvalidLevelError: If level is not a recognized value.
+    """
+    _validate_coordinates(lat, lon)
+    if level is not None and level not in _VALID_LEVELS:
+        raise InvalidLevelError(
+            f"level must be one of {sorted(_VALID_LEVELS)} or None, got {level!r}"
+        )
+
+    data = _get_data()
+    point = shapely.Point(lon, lat)
+    candidates = data.tree.query(point, predicate="intersects")
+
+    if len(candidates) == 0:
+        return None
+
+    idx = int(candidates[0])
+    attrs = data.attributes
+
+    if level is None:
+        return {
+            "region": attrs["REGION"][idx],
+            "province": attrs["PROVINCIA"][idx],
+            "commune": attrs["COMUNA"][idx],
+            "region_code": attrs["CUT_REG"][idx],
+            "province_code": attrs["CUT_PROV"][idx],
+            "commune_code": attrs["CUT_COM"][idx],
+        }
+    if level == "region":
+        return {"region": attrs["REGION"][idx], "region_code": attrs["CUT_REG"][idx]}
+    if level == "province":
+        return {"province": attrs["PROVINCIA"][idx], "province_code": attrs["CUT_PROV"][idx]}
+    return {"commune": attrs["COMUNA"][idx], "commune_code": attrs["CUT_COM"][idx]}

chile_reverse_geocoder/loader.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+import shapely
+import pyarrow.parquet as pq
+
+_DATA_PATH = Path(__file__).parent / "data" / "dpa.parquet"
+
+_FIELDS = ("CUT_REG", "CUT_PROV", "CUT_COM", "REGION", "PROVINCIA", "COMUNA")
+
+
+@dataclass(slots=True, frozen=True)
+class GeocoderData:
+    tree: shapely.STRtree
+    attributes: dict[str, list]
+
+
+def load_data() -> GeocoderData:
+    table = pq.read_table(_DATA_PATH, columns=[*_FIELDS, "geometry"])
+    geometries = shapely.from_wkb(table["geometry"].to_pylist())
+    tree = shapely.STRtree(geometries)
+    attributes = {f: table[f].to_pylist() for f in _FIELDS}
+    return GeocoderData(tree=tree, attributes=attributes)

chile_reverse_geocoder-0.1.0.dist-info/METADATA

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: chile-reverse-geocoder
+Version: 0.1.0
+Summary: Offline administrative reverse geocoding for Chile (region, province, commune)
+Author-email: Gonzalo Sepúlveda Navarrete <sepulveda.navarrete1996@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Gonzalo Sepúlveda Navarrete
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/gonzalosn/chile-reverse-geocoder
+Project-URL: Bug Tracker, https://github.com/gonzalosn/chile-reverse-geocoder/issues
+Keywords: geocoding,chile,reverse-geocoding,gis,offline,spatial
+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: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: shapely>=2.0
+Requires-Dist: pyogrio>=0.9
+Requires-Dist: pyarrow>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# chile-reverse-geocoder
+
+Reverse geocoding administrativo offline para Chile. Dado un par de coordenadas (lat, lon), retorna la región, provincia y comuna sin necesidad de API externa ni conexión a internet.
+
+## Fuente de datos
+
+Esta librería utiliza como base la capa oficial **División Política Administrativa (DPA) 2023** publicada por la Infraestructura de Datos Geoespaciales de Chile [IDE Chile](https://geoportal.cl/geoportal/catalog/36391/Divisi%C3%B3n%20Pol%C3%ADtica%20Administrativa%202023)
+
+Los límites administrativos y códigos territoriales corresponden a la cartografía oficial distribuida por IDE Chile.
+
+Fuente:
+
+* IDE Chile — División Político Administrativa (DPA)
+
+Los datos fueron procesados para su uso offline mediante:
+
+* eliminación de atributos no utilizados,
+* simplificación de geometrías,
+* conversión a formato GeoParquet,
+* construcción de índice espacial.
+
+Las modificaciones realizadas corresponden únicamente al formato y optimización del almacenamiento; la fuente original y propiedad de los datos permanecen con el organismo correspondiente.
+
+Consulte la licencia y condiciones de uso del dataset original antes de reutilizar los datos.
+
+
+## Instalación
+
+```bash
+pip install chile-reverse-geocoder
+```
+
+## Uso básico
+
+```python
+from chile_reverse_geocoder import lookup
+
+result = lookup(-33.4489, -70.6693)
+print(result)
+# {
+#   "region": "Metropolitana de Santiago",
+#   "province": "Santiago",
+#   "commune": "Santiago",
+#   "region_code": "13",
+#   "province_code": "131",
+#   "commune_code": "13101"
+# }
+```
+
+## Filtrar por nivel administrativo
+
+```python
+# Solo región
+lookup(-33.4489, -70.6693, level="region")
+# {"region": "Metropolitana de Santiago", "region_code": "13"}
+
+# Solo provincia
+lookup(-33.4489, -70.6693, level="province")
+# {"province": "Santiago", "province_code": "131"}
+
+# Solo comuna
+lookup(-33.4489, -70.6693, level="commune")
+# {"commune": "Santiago", "commune_code": "13101"}
+```
+
+## Casos especiales
+
+```python
+# Coordenadas fuera de Chile → None
+lookup(-34.6037, -58.3816)  # Buenos Aires → None
+
+# Coordenadas inválidas → excepción
+from chile_reverse_geocoder import InvalidCoordinatesError
+lookup(91.0, 0.0)  # raises InvalidCoordinatesError
+
+# Nivel inválido → excepción
+from chile_reverse_geocoder import InvalidLevelError
+lookup(-33.4489, -70.6693, level="city")  # raises InvalidLevelError
+```
+
+## Descripción técnica
+
+- **Offline**: No realiza llamadas a servicios externos. Los datos están empaquetados dentro de la librería (~2 MB).
+- **Sin API keys**: No requiere configuración de credenciales.
+- **Índice espacial STRtree**: Usa `shapely.STRtree` para búsqueda espacial eficiente O(log n). El índice se construye una sola vez (lazy loading) y se reutiliza en llamadas sucesivas mediante un singleton en memoria.
+- **Datos**: División Político-Administrativa (DPA) de Chile con 345 comunas. Almacenado en formato GeoParquet con geometrías simplificadas.
+
+## Dependencias
+
+- `shapely >= 2.0`
+- `pyogrio >= 0.9`
+- `pyarrow >= 13.0`
+
+## Licencia
+
+MIT
+
+Los datos administrativos incluidos o derivados mantienen las condiciones de uso establecidas por la fuente oficial correspondiente (IDE Chile).

chile_reverse_geocoder-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+chile_reverse_geocoder/__init__.py,sha256=qywCsUy-L3-VtUiaLLPZyma5Lc5ZWJTlfwzmChAhVRc,271
+chile_reverse_geocoder/exceptions.py,sha256=BBL430U7bgjijgynvePVVTW81merEF_IHA799lMiIyY,279
+chile_reverse_geocoder/geocoder.py,sha256=VvCq_ClFqanm400hyZPNj-o0N0xIg_lPGK2nNDHa__M,2812
+chile_reverse_geocoder/loader.py,sha256=7rgOxty0M4TI41flZDp0CTw9fQ-KpBypLXdlL3Anvis,723
+chile_reverse_geocoder/data/dpa.parquet,sha256=sjczq6n1AlizOUEVmdVlnFCek2Sxpo85d4Vpa-woY9k,3235801
+chile_reverse_geocoder-0.1.0.dist-info/licenses/LICENSE,sha256=CUC08lwt7oaJ_a2sPCMCR-9JjGz5Y0htvaiUm-5we5M,1085
+chile_reverse_geocoder-0.1.0.dist-info/licenses/NOTICE,sha256=hYDt1l3GzeWC8HmeJhR30E6tGGR8asTnmlECnh_d2p4,532
+chile_reverse_geocoder-0.1.0.dist-info/METADATA,sha256=AAzT04Lzv1E1p5HfWf7fI438X8uctKz9AFOofGsXLg8,5709
+chile_reverse_geocoder-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+chile_reverse_geocoder-0.1.0.dist-info/top_level.txt,sha256=Wd9asf2QSE1-l1kTHizYUbXjzwrmf7bSIbzSRYqTgqg,23
+chile_reverse_geocoder-0.1.0.dist-info/RECORD,,

chile_reverse_geocoder-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

chile_reverse_geocoder-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gonzalo Sepúlveda Navarrete
+
+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.

chile_reverse_geocoder-0.1.0.dist-info/licenses/NOTICE

@@ -0,0 +1,17 @@
+NOTICE
+
+This package includes administrative boundary data derived from the official División Política Administrativa (DPA) dataset published by IDE Chile.
+
+Source:
+https://www.geoportal.cl/
+
+The original geographic data remains subject to its original licensing and usage terms.
+
+Transformations applied by this project:
+
+* Removed unused attributes
+* Simplified geometries
+* Converted to GeoParquet
+* Built spatial index for offline reverse geocoding
+
+No changes were made to the administrative meaning of the original dataset.

chile_reverse_geocoder-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+chile_reverse_geocoder