# 🗺️ Optimizador de Rutas y Distancias de Reparto (Google Maps Distance Matrix API)

> **Resumen para No Técnicos**: Permite que tu Inteligencia Artificial calcule en segundos las distancias exactas, los tiempos de viaje considerando el tráfico real y el costo estimado de combustible o flete entre tu bodega y las direcciones de entrega de tus clientes en cualquier ciudad de América Latina.

| Metadato | Detalle |
|---|---|
| **Tipo** | API REST Oficial de Geolocalización y Rutas |
| **Área Empresarial** | 05. Operaciones, Logística y Distribución Urbana |
| **Nivel de Dificultad** | 🟢 Fácil |
| **Modelo de Costo** | Google Cloud otorga **$200 USD de crédito gratuito cada mes** (suficiente para más de 25,000 cálculos de distancia mensuales sin pagar un solo dólar) |
| **Enlace Oficial** | [Google Maps Platform - Distance Matrix API](https://developers.google.com/maps/documentation/distance-matrix) |

---

## 💡 ¿Para qué le sirve a tu empresa? (Valor Real)

Si tu negocio reparte productos a domicilio o envía técnicos a realizar servicios (reparaciones, instalaciones, catering, mensajería urbana):
- Sabes que el tráfico en ciudades como CDMX, Bogotá, Lima o Santiago puede duplicar los tiempos de entrega.
- Cobrar una tarifa fija de flete cuando un cliente está a 20 km de distancia puede hacerte perder dinero.

Con **Google Maps Distance Matrix API**:
- La IA calcula la distancia real en kilómetros y el tiempo estimado en hora pico.
- Calcula el flete justo: *"Para tu dirección en la Zona Norte, el costo de entrega es de $15.000 COP y tardará 45 minutos"*.
- Sugiere el orden óptimo de paradas para que tu repartidor haga la ruta más corta y gaste menos combustible.

---

## 🎁 ¿Qué valor aporta frente a soluciones tradicionales?

- **Datos de Tráfico en Tiempo Real**: Considera obras viales, trancones y horas de mayor congestión.
- **Validación y Corrección de Direcciones**: Corrige errores comunes de nomenclatura en direcciones latinoamericanas (Calles, Carreras, Colonias, Manzanas).
- **Ahorro Directo de Gasolina**: Reduce hasta un 25% los kilómetros recorridos por día.

---

## 🔑 ¿Qué necesitas para activarlo?

1. Una cuenta de Google Cloud Platform (GCP).
2. Habilitar la *Distance Matrix API* y *Geocoding API*.
3. Tu clave de API (`GOOGLE_MAPS_API_KEY`).

---

## ⚙️ Configuración Paso a Paso

Variables de entorno para tus aplicaciones o servidores:

```env
# Variables de entorno (.env)
GOOGLE_MAPS_API_KEY=tu_clave_google_maps_aqui
DIRECCION_BODEGA_ORIGEN=Av. Insurgentes Sur 1602, Ciudad de México
COSTO_POR_KILOMETRO_LOCAL=12.50 # En moneda local
```

---

## 🤖 Consultor Interactivo (Prompt Guiado para tu IA)

Copia y pega este prompt en tu chat con la IA:

```markdown
Actúa como mi Coordinador de Logística y Despachos.
Vamos a calcular el costo de flete y la ruta óptima para un lote de entregas del día.

Por favor, pregúntame:
1. ¿Cuál es la dirección de origen (nuestra bodega o tienda)?
2. ¿Cuáles son las direcciones de destino de los clientes a visitar hoy?
3. ¿Cuál es nuestra tarifa base de flete y el costo por kilómetro adicional?
4. ¿Existe alguna restricción de horario (ej: entregar antes de las 2:00 PM)?

Con tus datos, consultaré la API de Google Maps, calcularé el kilometraje total, ordenaré las paradas de la más cercana a la más lejana y te entregaré la hoja de ruta lista para el repartidor.
```

---

## 🌎 Caso de Uso Real en América Latina

**Empresa**: "Agua Purificada Los Manantiales" (Reparto de bidones de agua en San Salvador de Jujuy, Argentina).
- **Problema**: Los choferes cruzaban la ciudad de un extremo a otro sin orden, gastando demasiado combustible y llegando tarde a los clientes.
- **Resultado con la API**: La IA agrupa los pedidos por zonas y define el circuito más eficiente de la mañana. Redujeron el gasto de combustible en un 22% y aumentaron las entregas diarias de 45 a 65 bidones por camión.

---

## 🛡️ Consideraciones de Costos y Buenas Prácticas

- **Aprovecha el Crédito Gratuito**: Con los $200 USD mensuales que Google regala a todas las cuentas, el 99% de las pequeñas empresas nunca pagan nada.
- **Restricción de API Key**: En la consola de Google Cloud, restringe tu clave para que solo funcione con las APIs de Maps seleccionadas y evita usos no autorizados.