🌍 Geocoding API

Un servicio de geocodificación inversa basado en FastAPI que integra múltiples proveedores, incluyendo Geoapify, HERE y Nominatim. Esta API permite consultas de geolocalización dinámicas y flexibles, asegurando una configuración automatizada basada en el entorno.

🔥 Características Clave

Soporte multi-proveedor: Consulta diferentes servicios de geocodificación dinámicamente.
Configuración automatizada: Detecta y registra los geocodificadores usando variables de entorno.
Selección de proveedor flexible: Elige cualquier proveedor disponible o usa los predeterminados.
Alto rendimiento con FastAPI: Construido con FastAPI para escalabilidad y velocidad.

📝 Documentación Interactiva con FastAPI

El proyecto utiliza FastAPI para generar automáticamente la documentación interactiva de la API, siguiendo el estándar OpenAPI. Esto facilita la exploración, prueba y consumo de los endpoints. La documentación incluye descripciones de cada endpoint, parámetros de entrada y modelos de respuesta.

Documentación de la API generada por FastAPI

📦 Arquitectura de Caché de Dos Niveles

Para optimizar el rendimiento y reducir los costos de las llamadas a los servicios externos de geocodificación, el proyecto implementa una arquitectura de caché de dos niveles:

Redis (Caché L1 - Velocidad): Se utiliza para almacenar las respuestas de manera temporal (24 horas) y así poder servir las consultas más recientes de forma rápida.
SQLite (Caché L2 - Persistencia): Actúa como una caché a largo plazo. Si una consulta no se encuentra en Redis, se busca en la base de datos SQLite y, si se encuentra, se "promueve" de nuevo a Redis para futuras consultas rápidas.

Esta estrategia ayuda a ahorrar tokens y a minimizar las latencias en las consultas repetidas.

⚙️ Instalación

Clona el repositorio:
```
git clone https://github.com/xeland314/geocoding_api.git
cd geocoding_api
```
bash

Crea un entorno virtual:

python -m venv .venv
source .venv/bin/activate

bash

Instala las dependencias:
```
pip install -r pyproject.toml
```
bash

🌍 Configuración de Entorno

Configura las claves de API usando variables de entorno:

export GEOAPIFY_API_KEY="your_api_key"
export HERE_API_KEY="your_api_key"
export NOMINATIM_USER_AGENT="MyGeocoderApp/1.0"
export NOMINATIM_REVERSER_REPLICA_URL_1="http://127.0.0.1:8088/reverse"
export NOMINATIM_REVERSER_REPLICA_URL_2="http://127.0.0.1:8089/reverse"

bash

Alternativamente, usa el script `set_env.sh` proporcionado:

source ./scripts/set_env.sh

bash

🚀 Ejecutando la API

Inicia el servidor de FastAPI:

uvicorn main:app --host 0.0.0.0 --port 8000 --reload

bash

Documentación interactiva de la API disponible en:
🔗 http://127.0.0.1:8000/docs

📡 Endpoints de la API

🔎 Geocodificación Inversa

Realiza geocodificación inversa especificando latitud, longitud y un proveedor opcional:

curl -X GET "http://127.0.0.1:8000/reverse-geocode?latitude=40.748817&longitude=-73.985428&platform=geoapify"

bash

Respuesta de ejemplo:

{
  "success": true,
  "data": [
    {
      "formatted_address": "Empire State Building, 350 5th Ave, New York, NY, USA",
      "postcode": "10118",
      "country": "US",
      "state": "New York",
      "district": "Manhattan",
      "settlement": "New York",
      "street": "5th Ave",
      "house": "350"
    }
  ],
  "error": null
}

json

📜 Listar Proveedores Disponibles

Recupera la lista de geocodificadores registrados dinámicamente:

curl -X GET "http://127.0.0.1:8000/geocoders"

bash

Respuesta de ejemplo:

{
  "geocoders": [
    {
      "name": "GEOAPIFY",
      "url": "https://api.geoapify.com/v1/geocode/reverse"
    },
    {
      "name": "HERE",
      "url": "https://revgeocode.search.hereapi.com/v1/revgeocode"
    },
    {
      "name": "NOMINATIM",
      "url": "https://nominatim.openstreetmap.org/reverse"
    },
    {
      "name": "NOMINATIM_REPLICA_1",
      "url": "http://127.0.0.1:8088/reverse"
    }
  ]
}

json

📄 Licencia

Este proyecto está bajo la licencia GNU General Public License v3 (GPLv3). Eres libre de usar, modificar y distribuir este proyecto bajo los términos de la licencia GPLv3.

Consulta el archivo LICENSE para más detalles.

⚠️ Descargo de Responsabilidad

Este proyecto integra servicios de geocodificación de terceros (HERE, Geoapify, Nominatim). Los usuarios deben cumplir con los términos de servicio y los límites de uso de cada proveedor. El autor de este proyecto no avala ni facilita ninguna violación de los acuerdos de API externos.