geofinder-icgc 2.4.0

Geocodificador asíncrono para Cataluña usando el servicio ICGC

GeoFinder-ICGC

Geocodificador para Cataluña usando el servicio del ICGC (Institut Cartogràfic i Geològic de Catalunya). 🔄 API dual: Async nativo + wrappers sync para scripts simples.

---

GeoFinder-ICGC es un geocodificador avanzado para Cataluña diseñado para ser robusto, rápido y fácil de usar.

🚀 Instalación

# Instalación básica
pip install geofinder-icgc

# Con soporte para transformación de coordenadas (recomendado)
pip install geofinder-icgc[pyproj]

# Con soporte para servidor MCP (integración con IA)
pip install geofinder-icgc[mcp]

📖 Inicio Rápido

Uso Síncrono (Scripts sencillos)

from geofinder import GeoFinder

gf = GeoFinder()
results = gf.find_sync("Barcelona")

for r in results:
    print(f"{r.nom} ({r.nomTipus}) - {r.x}, {r.y}")

Uso Asíncrono (Alto rendimiento)

import asyncio
from geofinder import GeoFinder

async def main():
    async with GeoFinder() as gf:
        results = await gf.find("Diagonal 100, Barcelona")
        print(f"Encontrados: {len(results)}")

asyncio.run(main())

🔍 Manual de Funcionalidades

1. Búsqueda General (find / find_sync)

Detecta automáticamente el tipo de búsqueda según la entrada:

• Topónimos: "Montserrat", "Girona"
• Direcciones: "Carrer Aragó 50, Barcelona", "Gran Via 123"
• Coordenadas: "430000 4580000 EPSG:25831", "2.17 41.38 EPSG:4326"
• Carreteras: "C-32 km 10"
• Rectángulos: "X1 Y1 X2 Y2"

2. Geocodificación Inversa (find_reverse / find_reverse_sync)

Encuentra lugares o direcciones a partir de coordenadas.

# Soporta EPSG:25831 (por defecto) y EPSG:4326 (GPS)
results = await gf.find_reverse(430000, 4580000)

3. Autocompletado (autocomplete / autocomplete_sync)

Ideal para implementar buscadores en tiempo real.

suggestions = await gf.autocomplete("Barcel")

4. Búsqueda de Proximidad (search_nearby)

Encuentra lugares en un radio determinado alrededor de un punto de referencia.

# Busca todo en un radio de 2km de la Sagrada Família
nearby = await gf.search_nearby("Sagrada Família, Barcelona", radius_km=2.0)

5. Procesamiento por Lotes (find_batch / find_reverse_batch)

Ejecuta múltiples consultas en paralelo optimizando la concurrencia.

queries = ["Barcelona", "Girona", "Lleida", "Tarragona"]
batch_results = await gf.find_batch(queries, max_concurrency=10)

6. Obtención de Respuestas con Metadatos (find_response)

Devuelve un objeto GeoResponse que incluye los resultados y metadatos de rendimiento como el tiempo de ejecución.

⚙️ Configuración

El constructor de GeoFinder permite ajustar el comportamiento de la librería:

Parámetro	Tipo	Descripción
timeout	int	Tiempo máximo de espera (defecto: 5s).
cache_size	int	Capacidad de la caché LRU (defecto: 128).
cache_ttl	int	Tiempo de vida de la caché en segundos (defecto: 3600).
max_retries	int	Número de reintentos en caso de fallo (defecto: 3).
verify_ssl	bool	Verificar certificados SSL (defecto: True).

---

📚 Documentación

• COOKBOOK.md - Tutoriales y ejemplos prácticos
• README-DEV.md - Guía de desarrollo
• README-MCP.md - Servidor MCP
• README-ARQ.md - Arquitectura técnica

---

📚 Recursos

• Documentación ICGC
• Repositorio GitHub
• Issues
• Model Context Protocol (para MCP)

---

⚖️ Licencia

Distribuido bajo la licencia GPL-2.0-or-later. Basado en el trabajo original del ICGC adaptado para uso standalone.

---

© 2025 ICGC / Adaptado por Goalnefesh

Els petits canvis son poderosos 🤘