chile-reverse-geocoder 0.1.0

Offline administrative reverse geocoding for Chile (region, province, commune)

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

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

pip install chile-reverse-geocoder

Uso básico

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

# 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

# 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).