🗺️ API de Geolocalización

{
  "results": [
    {
      // Dirección formateada por Google (estandarizada)
      "formatted_address": "Biblioteca Vasconcelos, Eje 1 Norte, Buenavista, 06350 Ciudad de México, CDMX, México",
      
      // Información geométrica (coordenadas y tipo de ubicación)
      "geometry": {
        "location": {
          "lat": 19.4395418,  // Latitud (Norte-Sur: -90 a +90)
          "lng": -99.1520794  // Longitud (Este-Oeste: -180 a +180)
        },
        // Tipo de precisión de la ubicación
        "location_type": "ROOFTOP",  // ROOFTOP (preciso) | RANGE_INTERPOLATED | GEOMETRIC_CENTER | APPROXIMATE
        
        // Área rectangular que contiene toda la ubicación
        "viewport": {
          "northeast": { "lat": 19.4408907, "lng": -99.1507304 },
          "southwest": { "lat": 19.4381927, "lng": -99.1534284 }
        },
        
        // Área precisa del lugar (opcional)
        "bounds": {
          "northeast": { "lat": 19.4408907, "lng": -99.1507304 },
          "southwest": { "lat": 19.4381927, "lng": -99.1534284 }
        }
      },
      
      // ID único de Google Maps para este lugar
      "place_id": "ChIJXxQBnbP_0YURW9JOEKiHlBM",  // Identificador permanente
      
      // Componentes individuales de la dirección
      "address_components": [
        {
          "long_name": "Biblioteca Vasconcelos",
          "short_name": "Biblioteca Vasconcelos",
          "types": ["establishment", "library", "point_of_interest"]
        },
        {
          "long_name": "Eje 1 Norte",
          "short_name": "Eje 1 Nte",
          "types": ["route"]
        },
        {
          "long_name": "Buenavista",
          "short_name": "Buenavista",
          "types": ["neighborhood", "political"]
        },
        {
          "long_name": "Ciudad de México",
          "short_name": "CDMX",
          "types": ["locality", "political"]
        },
        {
          "long_name": "México",
          "short_name": "MX",
          "types": ["country", "political"]
        },
        {
          "long_name": "06350",
          "short_name": "06350",
          "types": ["postal_code"]
        }
      ],
      
      // Tipos de este lugar (puede ser múltiples)
      "types": ["library", "point_of_interest", "establishment"]
    }
  ],
  
  // Estado de la respuesta
  "status": "OK"  // OK | ZERO_RESULTS | OVER_QUERY_LIMIT | REQUEST_DENIED | INVALID_REQUEST
}

# Activar entorno virtual
.\venv\Scripts\Activate

# Instalar googlemaps para Python
pip install googlemaps==4.10.0  # Cliente oficial de Google Maps

# Instalar geopy para geocodificación
pip install geopy==2.4.0  # Biblioteca de geocodificación

# Actualizar requirements.txt
pip freeze > requirements.txt  # Guarda todas las dependencias

# Si quieres mayor seguridad, usa variables de entorno:
import os
GOOGLE_MAPS_API_KEY = os.environ.get('GOOGLE_MAPS_API_KEY', '')  # Lee de variable de entorno

# O usando python-decouple:
from decouple import config
GOOGLE_MAPS_API_KEY = config('GOOGLE_MAPS_API_KEY')  # Lee de archivo .env

from django.db import models
from decimal import Decimal

class Biblioteca(models.Model):
    """Modelo para bibliotecas con ubicación geográfica"""
    
    nombre = models.CharField(max_length=200)  # Nombre de la biblioteca
    direccion = models.CharField(max_length=300)  # Dirección postal
    ciudad = models.CharField(max_length=100)  # Ciudad
    pais = models.CharField(max_length=100, default='México')  # País
    
    # Coordenadas geográficas (se llenan automáticamente)
    latitud = models.DecimalField(
        max_digits=10, 
        decimal_places=7, 
        null=True, 
        blank=True
    )  # Latitud con 7 decimales de precisión
    
    longitud = models.DecimalField(
        max_digits=10, 
        decimal_places=7, 
        null=True, 
        blank=True
    )  # Longitud con 7 decimales de precisión
    
    # Datos adicionales de Google Maps
    place_id = models.CharField(max_length=200, blank=True)  # ID único de Google
    google_maps_url = models.URLField(blank=True)  # URL de Google Maps
    
    telefono = models.CharField(max_length=20, blank=True)  # Teléfono
    horario = models.TextField(blank=True)  # Horario de atención
    
    class Meta:
        verbose_name = 'Biblioteca'
        verbose_name_plural = 'Bibliotecas'
        ordering = ['nombre']
    
    def __str__(self):
        return self.nombre
    
    @property
    def direccion_completa(self):
        """Retorna dirección formateada"""
        return f"{self.direccion}, {self.ciudad}, {self.pais}"  # Dirección completa
    
    def generar_google_maps_url(self):
        """
        Genera URL de Google Maps basada en las coordenadas
        
        Formatos disponibles:
        1. Con Place ID (más preciso): https://www.google.com/maps/place/?q=place_id:ChIJ...
        2. Con coordenadas: https://www.google.com/maps?q=lat,lng
        3. Con búsqueda: https://www.google.com/maps/search/?api=1&query=nombre+direccion
        """
        if self.place_id:
            # Opción 1: Usar Place ID (más preciso)
            return f"https://www.google.com/maps/place/?q=place_id:{self.place_id}"
        elif self.latitud and self.longitud:
            # Opción 2: Usar coordenadas
            return f"https://www.google.com/maps?q={self.latitud},{self.longitud}"
        else:
            # Opción 3: Búsqueda por texto
            import urllib.parse
            query = urllib.parse.quote(self.direccion_completa)
            return f"https://www.google.com/maps/search/?api=1&query={query}"
    
    def geocodificar(self):
        """Obtiene coordenadas de la dirección"""
        from .services import GoogleMapsService
        
        resultado = GoogleMapsService.geocodificar_direccion(self.direccion_completa)
        
        if resultado:
            self.latitud = resultado['lat']  # Guarda latitud
            self.longitud = resultado['lng']  # Guarda longitud
            self.place_id = resultado.get('place_id', '')  # Guarda Place ID
            self.google_maps_url = self.generar_google_maps_url()  # ⭐ Genera URL automáticamente
            self.save()  # Guarda en la base de datos
            return True
        return False

import googlemaps
from django.conf import settings
from decimal import Decimal
import logging

logger = logging.getLogger(__name__)  # Logger para errores

class GoogleMapsService:
    """Servicio para interactuar con Google Maps API"""
    
    def __init__(self):
        self.client = googlemaps.Client(key=settings.GOOGLE_MAPS_API_KEY)  # Cliente de Google Maps
    
    @classmethod
    def geocodificar_direccion(cls, direccion):
        """
        Convierte dirección en coordenadas
        
        Args:
            direccion (str): Dirección completa
            
        Returns:
            dict: {'lat': float, 'lng': float, 'place_id': str}
        """
        try:
            service = cls()  # Instancia del servicio
            resultado = service.client.geocode(direccion)  # Llama a Geocoding API
            
            if resultado:  # Si encuentra resultados
                location = resultado[0]['geometry']['location']  # Obtiene ubicación
                place_id = resultado[0]['place_id']  # ID del lugar
                
                return {
                    'lat': Decimal(str(location['lat'])),  # Convierte a Decimal
                    'lng': Decimal(str(location['lng'])),  # Convierte a Decimal
                    'place_id': place_id,
                    'formatted_address': resultado[0]['formatted_address']  # Dirección formateada
                }
            
            return None  # No se encontró
            
        except Exception as e:
            logger.error(f"Error geocodificando: {e}")  # Registra error
            return None
    
    @classmethod
    def calcular_distancia(cls, origen, destino):
        """
        Calcula distancia entre dos puntos
        
        Args:
            origen (tuple): (lat, lng) del origen
            destino (tuple): (lat, lng) del destino
            
        Returns:
            dict: Información de distancia y duración
        """
        try:
            service = cls()
            resultado = service.client.distance_matrix(
                origins=[origen],  # Punto de inicio
                destinations=[destino],  # Punto de destino
                mode='driving',  # Modo: driving, walking, bicycling, transit
                language='es'  # Idioma español
            )
            
            if resultado['rows']:
                element = resultado['rows'][0]['elements'][0]
                
                if element['status'] == 'OK':
                    return {
                        'distancia_texto': element['distance']['text'],  # "15.2 km"
                        'distancia_metros': element['distance']['value'],  # 15200
                        'duracion_texto': element['duration']['text'],  # "25 mins"
                        'duracion_segundos': element['duration']['value']  # 1500
                    }
            
            return None
            
        except Exception as e:
            logger.error(f"Error calculando distancia: {e}")
            return None

from rest_framework import viewsets
from rest_framework.decorators import action
from rest_framework.response import Response
from .models import Biblioteca
from .serializers import BibliotecaSerializer
from .services import GoogleMapsService

# (Ver código completo en PASO 6 arriba)

<!DOCTYPE html>
<html lang="es">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Mapa de Bibliotecas</title>
    
    <!-- Estilos CSS -->
    <style>
        /* Resetear estilos por defecto */
        * {
            margin: 0;
            padding: 0;
            box-sizing: border-box;
        }
        
        body {
            font-family: 'Segoe UI', Arial, sans-serif;
            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
            padding: 20px;
        }
        
        /* Contenedor principal */
        .container {
            max-width: 1200px;
            margin: 0 auto;
            background: white;
            border-radius: 15px;
            overflow: hidden;
            box-shadow: 0 20px 60px rgba(0,0,0,0.3);
        }
        
        /* Encabezado */
        .header {
            background: linear-gradient(135deg, #11998e 0%, #38ef7d 100%);
            color: white;
            padding: 30px;
            text-align: center;
        }
        
        /* El mapa ocupará 600px de alto y todo el ancho */
        #map {
            height: 600px;
            width: 100%;
        }
        
        /* Panel de información */
        .info-panel {
            padding: 20px;
            background: #f8f9fa;
        }
        
        /* Botones */
        .btn {
            background: #11998e;
            color: white;
            padding: 10px 20px;
            border: none;
            border-radius: 5px;
            cursor: pointer;
            margin: 5px;
        }
        
        .btn:hover {
            background: #0d7a6f;
        }
    </style>
</head>
<body>
    <div class="container">
        <!-- Encabezado -->
        <div class="header">
            <h1>🗺️ Mapa de Bibliotecas de México</h1>
            <p>Encuentra la biblioteca más cercana</p>
        </div>
        
        <!-- Panel de controles -->
        <div class="info-panel">
            <button class="btn" onclick="obtenerMiUbicacion()">
                📍 Usar mi ubicación actual
            </button>
            <button class="btn" onclick="cargarBibliotecas()">
                🔄 Recargar bibliotecas
            </button>
            <span id="contador" style="margin-left: 20px; font-weight: bold;">
                Bibliotecas cargadas: 0
            </span>
        </div>
        
        <!-- Contenedor del mapa (aquí se mostrará Google Maps) -->
        <div id="map"></div>
    </div>
    
    <!-- Cargar la API de Google Maps -->
    <!-- IMPORTANTE: Reemplaza TU_API_KEY con tu clave real -->
    <script src="https://maps.googleapis.com/maps/api/js?key=TU_API_KEY&callback=initMap"
            async defer></script>
    
    <!-- JavaScript para controlar el mapa -->
    <script>
        // ========================================
        // VARIABLES GLOBALES
        // ========================================
        
        let map;  // Variable que guardará el objeto del mapa
        let markers = [];  // Array para guardar todos los marcadores
        
        // ========================================
        // FUNCIÓN 1: Inicializar el mapa
        // Se ejecuta automáticamente cuando carga Google Maps
        // ========================================
        
        function initMap() {
            console.log('🗺️ Inicializando mapa...');
            
            // Crear el mapa centrado en Ciudad de México, México
            map = new google.maps.Map(document.getElementById('map'), {
                center: { 
                    lat: 19.4326,   // Latitud de Ciudad de México
                    lng: -99.1332   // Longitud de Ciudad de México
                },
                zoom: 4,  // Nivel de zoom (1 = mundo, 20 = edificio)
                
                // Opciones adicionales del mapa
                mapTypeControl: true,  // Mostrar botón para cambiar tipo de mapa
                streetViewControl: true,  // Mostrar botón Street View
                fullscreenControl: true,  // Botón de pantalla completa
                zoomControl: true  // Botones de zoom +/-
            });
            
            // Cargar las bibliotecas automáticamente al iniciar
            cargarBibliotecas();
        }
        
        // ========================================
        // FUNCIÓN 2: Cargar bibliotecas desde la API
        // ========================================
        
        async function cargarBibliotecas() {
            console.log('📚 Cargando bibliotecas desde la API...');
            
            try {
                // Hacer petición GET a nuestra API
                const response = await fetch('/api/bibliotecas/');
                
                // Verificar si la petición fue exitosa
                if (!response.ok) {
                    throw new Error('Error en la petición: ' + response.status);
                }
                
                // Convertir la respuesta a JSON
                const data = await response.json();
                
                console.log('✅ Datos recibidos:', data);
                
                // Limpiar marcadores anteriores
                limpiarMarcadores();
                
                // Contador de bibliotecas
                let contador = 0;
                
                // Crear un marcador para cada biblioteca
                data.forEach(biblioteca => {
                    // Solo crear marcador si tiene coordenadas
                    if (biblioteca.latitud && biblioteca.longitud) {
                        crearMarcador(biblioteca);
                        contador++;
                    }
                });
                
                // Actualizar contador en la página
                document.getElementById('contador').textContent = 
                    `Bibliotecas cargadas: ${contador}`;
                
            } catch (error) {
                console.error('❌ Error cargando bibliotecas:', error);
                alert('Error al cargar las bibliotecas. Verifica la consola.');
            }
        }
        
        // ========================================
        // FUNCIÓN 3: Crear marcador en el mapa
        // ========================================
        
        function crearMarcador(biblioteca) {
            // Crear el marcador (pin) en el mapa
            const marker = new google.maps.Marker({
                position: {
                    lat: parseFloat(biblioteca.latitud),  // Convertir string a número
                    lng: parseFloat(biblioteca.longitud)
                },
                map: map,  // En qué mapa mostrarlo
                title: biblioteca.nombre,  // Texto al pasar el mouse
                animation: google.maps.Animation.DROP  // Animación de caída
            });
            
            // Crear ventana de información (popup)
            const infoWindow = new google.maps.InfoWindow({
                content: `
                    <div style="padding: 10px; max-width: 250px;">
                        <h3 style="margin: 0 0 10px 0; color: #11998e;">
                            ${biblioteca.nombre}
                        </h3>
                        <p style="margin: 5px 0;">
                            <strong>📍 Dirección:</strong><br>
                            ${biblioteca.direccion}<br>
                            ${biblioteca.ciudad}, ${biblioteca.pais}
                        </p>
                        <p style="margin: 5px 0;">
                            <strong>📞 Teléfono:</strong><br>
                            ${biblioteca.telefono || 'No disponible'}
                        </p>
                        <p style="margin: 5px 0;">
                            <strong>🕒 Horario:</strong><br>
                            ${biblioteca.horario || 'No disponible'}
                        </p>
                        <p style="margin: 10px 0 0 0; font-size: 0.9em; color: #666;">
                            <strong>Coordenadas:</strong><br>
                            ${biblioteca.latitud}, ${biblioteca.longitud}
                        </p>
                        ${biblioteca.google_maps_url ? `
                            <p style="margin: 10px 0 0 0; text-align: center;">
                                <a href="${biblioteca.google_maps_url}" 
                                   target="_blank" 
                                   style="display: inline-block; 
                                          background: #11998e; 
                                          color: white; 
                                          padding: 8px 15px; 
                                          text-decoration: none; 
                                          border-radius: 5px;
                                          font-weight: bold;">
                                    🗺️ Abrir en Google Maps
                                </a>
                            </p>
                        ` : ''}
                    </div>
                `
            });
            
            // Al hacer clic en el marcador, mostrar la información
            marker.addListener('click', () => {
                // Cerrar todas las ventanas abiertas
                markers.forEach(m => {
                    if (m.infoWindow) {
                        m.infoWindow.close();
                    }
                });
                
                // Abrir esta ventana
                infoWindow.open(map, marker);
                
                // Centrar el mapa en este marcador
                map.setCenter(marker.getPosition());
            });
            
            // Guardar referencia a la ventana de información
            marker.infoWindow = infoWindow;
            
            // Agregar el marcador al array
            markers.push(marker);
        }
        
        // ========================================
        // FUNCIÓN 4: Obtener ubicación del usuario
        // ========================================
        
        function obtenerMiUbicacion() {
            console.log('📍 Obteniendo ubicación del usuario...');
            
            // Verificar si el navegador soporta geolocalización
            if (navigator.geolocation) {
                navigator.geolocation.getCurrentPosition(
                    // Éxito: se obtuvo la ubicación
                    (position) => {
                        const pos = {
                            lat: position.coords.latitude,
                            lng: position.coords.longitude
                        };
                        
                        console.log('✅ Ubicación obtenida:', pos);
                        
                        // Centrar el mapa en la ubicación del usuario
                        map.setCenter(pos);
                        map.setZoom(15);
                        
                        // Crear marcador "Estoy aquí"
                        new google.maps.Marker({
                            position: pos,
                            map: map,
                            title: 'Mi ubicación',
                            icon: {
                                url: 'http://maps.google.com/mapfiles/ms/icons/blue-dot.png'
                            }
                        });
                    },
                    // Error: no se pudo obtener la ubicación
                    (error) => {
                        console.error('❌ Error obteniendo ubicación:', error);
                        alert('No se pudo obtener tu ubicación. Verifica los permisos.');
                    }
                );
            } else {
                alert('Tu navegador no soporta geolocalización');
            }
        }
        
        // ========================================
        // FUNCIÓN 5: Limpiar todos los marcadores
        // ========================================
        
        function limpiarMarcadores() {
            // Remover cada marcador del mapa
            markers.forEach(marker => {
                marker.setMap(null);
            });
            
            // Vaciar el array
            markers = [];
        }
        
    </script>
</body>
</html>

@classmethod
def buscar_lugares_cercanos(cls, lat, lng, tipo='library', radio=5000):
    """
    Busca lugares cercanos a una ubicación
    
    Args:
        lat: Latitud
        lng: Longitud
        tipo: Tipo de lugar (library, restaurant, school, etc.)
        radio: Radio de búsqueda en metros
    """
    try:
        service = cls()
        resultado = service.client.places_nearby(
            location=(float(lat), float(lng)),  # Ubicación central
            radius=radio,  # Radio en metros
            type=tipo  # Tipo de lugar
        )
        
        lugares = []
        for place in resultado.get('results', []):
            lugares.append({
                'nombre': place.get('name'),
                'direccion': place.get('vicinity'),
                'rating': place.get('rating', 0),
                'place_id': place.get('place_id'),
                'lat': place['geometry']['location']['lat'],
                'lng': place['geometry']['location']['lng']
            })
        
        return lugares
        
    except Exception as e:
        logger.error(f"Error buscando lugares: {e}")
        return []

function mostrarRuta(origen, destino) {
    // Crear servicio de direcciones
    const directionsService = new google.maps.DirectionsService();
    const directionsRenderer = new google.maps.DirectionsRenderer();
    
    directionsRenderer.setMap(map);  // Asocia al mapa
    
    // Solicitar ruta
    directionsService.route({
        origin: origen,  // Punto de inicio
        destination: destino,  // Punto de destino
        travelMode: google.maps.TravelMode.DRIVING  // Modo: DRIVING, WALKING, BICYCLING, TRANSIT
    }, (response, status) => {
        if (status === 'OK') {
            directionsRenderer.setDirections(response);  // Dibuja la ruta
            
            // Obtener información de la ruta
            const route = response.routes[0].legs[0];
            console.log(`Distancia: ${route.distance.text}`);  // Muestra distancia
            console.log(`Duración: ${route.duration.text}`);  // Muestra tiempo
        } else {
            console.error('Error calculando ruta:', status);
        }
    });
}