Bogotá Apartments Dataset

---

🏢 Análisis Completo del Mercado Inmobiliario de Bogotá

Dataset actualizado con datos históricos y análisis predictivo en tiempo real

📊 Estado del Proyecto

Métrica	Valor
Última Actualización	📅 1 de Diciembre 2024
Versión Actual	🚀 v3.0.0
Próxima Versión	🔧 v3.1.0 (En desarrollo)
Inicio del Proyecto	📅 Julio 2024
Apartamentos Procesados	📈 1,000+ → 20,000+ (V3.1.0)
Fuentes de Datos	🌐 2 sitios
Frecuencia de Actualización	⏰ Cada 3 semanas

🎯 Descripción del Proyecto

Bogotá Apartments es una plataforma de datos de código abierto especializada en el análisis integral del mercado inmobiliario de Bogotá, Colombia. Utilizamos técnicas avanzadas de web scraping, machine learning y procesamiento geoespacial para generar insights valiosos sobre tendencias de precios, patrones de ubicación y características del mercado inmobiliario bogotano.

🔍 Características Principales

• 🔄 Actualización Automática: Datos frescos cada 3 semanas con validación automática
• 📈 Análisis Histórico: Seguimiento temporal de precios con más de 6 meses de historia
• 🗺️ Análisis Geoespacial: Coordenadas precisas con análisis de proximidad a TransMilenio y parques
• 🏗️ Arquitectura Escalable: Construido con Scrapy + MongoDB + ETL automatizado
• 📊 Dashboards Interactivos: Visualizaciones en tiempo real y reportes ejecutivos
• 🤖 ML Ready: Datos pre-procesados listos para modelos de machine learning

---

📚 Tabla de Contenidos

• 🚀 Inicio Rápido
• ⚙️ Configuración
• 📊 Fuentes de Datos
• 📁 Estructura de Datos
• 🔄 Actualización de Datos
• 📈 Dashboards y Visualizaciones
• 🏗️ Arquitectura del Proyecto
• 🤝 Contribuir
• 📊 Datos Históricos
• 📄 Licencia
• 👥 Equipo

---

🚀 Inicio Rápido

📥 Descargar Datos Más Recientes

# Versión 3.0.0 - Diciembre 2024
wget https://github.com/builker-col/bogota-apartments/releases/download/v3.0.0/processed_v3.0.0_december_2024.json

# Alternativamente usando curl
curl -L -o apartments_v3.json https://github.com/builker-col/bogota-apartments/releases/download/v3.0.0/processed_v3.0.0_december_2024.json

🛠️ Instalación del Entorno

# Clonar el repositorio
git clone https://github.com/builker-col/bogota-apartments.git
cd bogota-apartments

# Crear entorno virtual (recomendado)
python -m venv venv
source venv/bin/activate  # En Windows: venv\Scripts\activate

# Instalar dependencias principales
pip install -r requirements.txt

# Instalar dependencias de análisis de datos (opcional)
pip install -r requirements_data_analysis.txt

⚡ Ejecución Rápida

# Ejecutar scraper completo
scrapy crawl habi_spider
scrapy crawl metrocuadrado_spider

# Procesar datos
python processing.py

---

⚙️ Configuración

🗄️ Configuración con MongoDB

Para utilizar MongoDB como base de datos, crea un archivo .env en la raíz del proyecto:

# Configuración de MongoDB
MONGO_URI=mongodb://localhost:27017/bogota_apartments
MONGO_DATABASE=bogota_apartments
MONGO_COLLECTION_RAW=scrapy_bogota_apartments
MONGO_COLLECTION_PROCESSED=scrapy_bogota_apartments_processed

# Configuración opcional de logging
LOG_LEVEL=INFO
SCRAPY_LOG_LEVEL=INFO

💾 Configuración Sin MongoDB

Para ejecutar sin MongoDB, modifica las siguientes líneas en bogota_apartments/settings.py:

# Comentar o eliminar estas líneas
# MONGO_URI = os.getenv('MONGO_URI')
# MONGO_DATABASE = os.getenv('MONGO_DATABASE')

# Comentar el pipeline de MongoDB
# ITEM_PIPELINES = {
#     'bogota_apartments.pipelines.MongoDBPipeline': 500
# }

# Habilitar pipeline de archivos JSON
ITEM_PIPELINES = {
    'bogota_apartments.pipelines.JsonWriterPipeline': 300
}

---

📊 Fuentes de Datos

🌐 Sitios Web Monitoreados

Plataforma	Tiempo por Propiedad	Tecnología Utilizada	Estado	Cobertura
Metrocuadrado	~0.194 segundos	Scrapy + Requests	✅ Activo	Toda Bogotá
Habi	~0.187 segundos	Scrapy + Selenium	✅ Activo	Zonas Premium

🛡️ Ética en Web Scraping: Todos los procesos de extracción respetan estrictamente los términos de servicio, políticas de robots.txt y límites de velocidad de cada sitio web. Implementamos delays inteligentes y rotación de User-Agents para minimizar el impacto en los servidores.

🏗️ Arquitectura Técnica

┌─────────────────┐    ┌──────────────┐    ┌─────────────────┐
│   Web Sources   │ -> │ Scrapy Core  │ -> │   Data Lake     │
│  • Metrocuadrado│    │ • Rate Limit │    │   (MongoDB)     │
│  • Habi         │    │ • Validation │    │                 │
└─────────────────┘    └──────────────┘    └─────────────────┘
                              │                       │
                              v                       v
                    ┌──────────────────┐    ┌─────────────────┐
                    │ ETL Processing   │    │   Analytics     │
                    │ • Geocoding      │    │   Dashboard     │
                    │ • Deduplication  │    │                 │
                    └──────────────────┘    └─────────────────┘

---

📁 Estructura de Datos

📊 Dataset Principal - Apartamentos

📂 Archivo: data/processed/apartments.csv | 📄 Formato: JSON/CSV
📈 Registros: 75,000+ apartamentos únicos
🔄 Actualización: Cada 3 semanas

📋 Esquema de Datos Completo

📋 Ver Estructura Completa de Campos (Click para expandir)

Información Básica

Campo	Tipo	Descripción	Ejemplo
codigo	String	Identificador único del apartamento	"APT_001_MTR_2024"
tipo_propiedad	String	Tipo de inmueble	"Apartamento", "Penthouse"
tipo_operacion	String	Modalidad comercial	"Venta", "Arriendo"
precio_venta	Integer	Precio de venta en COP	250000000
precio_arriendo	Integer	Precio de arriendo mensual en COP	1500000
area	Float	Área en metros cuadrados	85.5
habitaciones	Integer	Número de habitaciones	3
banos	Integer	Número de baños	2
administracion	Integer	Cuota de administración mensual	180000
parqueaderos	Integer	Número de parqueaderos	1

Ubicación y Contexto

Campo	Tipo	Descripción	Ejemplo
sector	String	Zona/Sector de ubicación	"Chapinero", "Zona Rosa"
localidad	String	Localidad de Bogotá	"Chapinero", "Usaquén"
barrio	String	Barrio específico	"Zona Rosa", "El Chicó"
estrato	Integer	Estrato socioeconómico (1-6)	4
longitud	Float	Coordenada geográfica	-74.0721
latitud	Float	Coordenada geográfica	4.6097
coords_modified	Boolean	Indica si las coordenadas fueron ajustadas	false

Características del Inmueble

Campo	Tipo	Descripción	Ejemplo
antiguedad	Integer	Años de construcción	5
estado	String	Estado del inmueble	"Usado", "Nuevo", "Sobre planos"
piso	Integer	Número de piso	12
closets	Integer	Número de closets	4

Amenidades y Servicios

Campo	Tipo	Descripción
jacuzzi	Boolean	Disponibilidad de jacuzzi
piscina	Boolean	Acceso a piscina
salon_comunal	Boolean	Salón comunal disponible
terraza	Boolean	Terraza privada
vigilancia	Boolean	Vigilancia privada 24/7
chimenea	Boolean	Chimenea disponible
permite_mascotas	Boolean	Política de mascotas
gimnasio	Boolean	Gimnasio en el edificio
ascensor	Boolean	Ascensor disponible
conjunto_cerrado	Boolean	Ubicado en conjunto cerrado

Análisis de Proximidad (Nuevo en v3.0.0)

Campo	Tipo	Descripción
estacion_tm_cercana	String	Estación de TransMilenio más cercana
distancia_estacion_tm_m	Float	Distancia en metros a TransMilenio
is_cerca_estacion_tm	Boolean	Dentro de 500m de TransMilenio
parque_cercano	String	Parque más cercano al apartamento
distancia_parque_m	Float	Distancia en metros al parque
is_cerca_parque	Boolean	Dentro de 500m de un parque
centro_comercial_cercano	String	Centro comercial más cercano
distancia_centro_comercial_m	Float	Distancia en metros al centro comercial
is_cerca_centro_comercial	Boolean	Dentro de 800m de un centro comercial

Metadatos y Tracking

Campo	Tipo	Descripción
website	String	Fuente de los datos
compañia	String	Inmobiliaria responsable
last_view	DateTime	Última verificación del scraper
timeline	Array	Historial de precios
url	String	URL original del anuncio
descripcion	Text	Descripción detallada
datetime	DateTime	Timestamp de extracción

⚠️ Consideraciones Importantes de Calidad de Datos

🎯 Coordenadas Geográficas: La columna coords_modified indica si las coordenadas fueron ajustadas algorítmicamente usando geocoding reverso. Un valor true sugiere validar la precisión para aplicaciones críticas de ubicación.

📅 Disponibilidad: El campo last_view se actualiza en cada ejecución del scraper y puede no reflejar la disponibilidad real del inmueble en el sitio web. Para verificar disponibilidad actual, consultar la URL original.

💰 Precios: Los precios están en pesos colombianos (COP) y reflejan el valor al momento de la extracción. Para análisis temporales, utilizar el campo timeline.

---

🔄 Actualización de Datos

📅 Cronograma de Actualizaciones

Frecuencia	Tipo	Descripción	Próxima Fecha
Semanal	Incremental	Nuevos apartamentos y actualizaciones de precio	Cada Lunes
Mensual	Completa	Validación y limpieza de datos históricos	1er día del mes
Trimestral	Release	Nueva versión con mejoras y análisis	Cada 3 meses

🔄 Proceso Automatizado

graph LR
    A[Scraping Automático] --> B[Validación de Calidad]
    B --> C[Procesamiento ETL]
    C --> D[Enriquecimiento Geoespacial]
    D --> E[Deduplicación]
    E --> F[Publicación Dataset]
    F --> G[Actualización Dashboards]

Loading

📊 Métricas de Calidad

• Completitud: >95% de campos requeridos completos
• Precisión Geográfica: >90% de coordenadas validadas
• Duplicados: <2% de registros duplicados
• Actualidad: Datos frescos cada 21 días máximo

---

📈 Dashboards y Visualizaciones

🎯 Dashboards Interactivos en Vivo

Plataforma	Tipo	Características	Enlace
MongoDB Charts	Profesional	Filtros avanzados, tiempo real	🔗 Ver Dashboard
GitHub Pages	Web Público	Análisis estático, mobile-friendly	🔗 Ver Análisis
Kaggle	Dataset	Kernels públicos, competencias	🔗 Explorar Datos

📊 Visualizaciones Destacadas

🎨 Tipos de Análisis Disponibles

• 📈 Evolución de Precios: Tendencias temporales por zona
• 🗺️ Mapas de Calor: Distribución geográfica de precios
• 📊 Análisis Comparativo: Precios por m² vs características
• 🎯 Análisis de Proximidad: Impacto de TransMilenio en precios
• 📉 Métricas de Mercado: Tiempo promedio en mercado por zona

---

🏗️ Arquitectura del Proyecto

📁 Estructura de Directorios

bogota-apartments/
├── 📂 bogota_apartments/          # Core Scrapy project
│   ├── spiders/                   # Web scrapers
│   │   ├── habi_spider.py        # Habi.co scraper
│   │   └── metrocuadrado_spider.py # Metrocuadrado scraper
│   ├── pipelines.py              # Data processing pipelines
│   ├── settings.py               # Scrapy configuration
│   ├── items.py                  # Data models
│   └── middlewares.py            # Custom middlewares
├── 📂 data/
│   ├── raw/                      # Raw scraped data
│   └── processed/                # Clean, analyzed datasets
├── 📂 ETL/                       # Data transformation scripts
│   ├── geocoding.py              # Coordinate enrichment
│   ├── deduplication.py          # Duplicate removal
│   └── proximity_analysis.py     # Distance calculations
├── 📂 notebooks/                 # Jupyter analysis notebooks
│   ├── price_analysis.ipynb      # Price trend analysis
│   ├── geographic_analysis.ipynb # Spatial analysis
│   └── market_insights.ipynb     # Market research
├── 📂 visualizations/            # Generated charts and graphs
├── 📂 docs/                      # Project documentation
└── 📂 tests/                     # Unit and integration tests

🔧 Tecnologías Utilizadas

Categoría	Tecnología	Versión	Uso
Web Scraping	Scrapy	2.5+	Framework principal
Web Driver	Selenium	4.0+	JavaScript rendering
Base de Datos	MongoDB	5.0+	Almacenamiento primario
Procesamiento	Pandas	1.5+	ETL y análisis
Geolocalización	GeoPandas	0.12+	Análisis espacial
Visualización	Plotly	5.0+	Gráficos interactivos

---

🤝 Contribuir

🚀 Cómo Participar

1. 🍴 Fork el repositorio en GitHub
2. 📥 Clona tu fork localmente

   git clone https://github.com/TU_USUARIO/bogota-apartments.git

3. 🌿 Crea una rama para tu feature

   git checkout -b feature/nueva-funcionalidad

4. 💻 Desarrolla y prueba tus cambios
5. ✅ Ejecuta las pruebas

   python -m pytest tests/

6. 📝 Commit con mensajes descriptivos

   git commit -m "feat: agregar análisis de precios por zona"

7. 🚀 Push a tu rama

   git push origin feature/nueva-funcionalidad

8. 🔄 Abre un Pull Request detallado

🎯 Áreas de Contribución Prioritarias

Área	Descripción	Nivel	Impacto
🔍 Nuevas Fuentes	Agregar scrapers para Fincaraiz, Ciencuadras	Intermedio	Alto
🤖 ML Models	Modelos predictivos de precios	Avanzado	Muy Alto
🗺️ Geo-Analytics	Análisis espacial avanzado	Intermedio	Alto
📊 Dashboards	Nuevas visualizaciones interactivas	Intermedio	Medio
🛠️ Performance	Optimizaciones de scraping	Avanzado	Alto
📚 Documentación	Tutoriales y guías	Principiante	Medio
🧪 Testing	Pruebas automatizadas	Intermedio	Alto

📋 Guidelines para Contribuidores

• 📝 Código: Seguir PEP 8 para Python
• 🧪 Tests: Incluir tests para nuevas funcionalidades
• 📚 Docs: Documentar nuevas APIs y cambios
• 🚀 Performance: Mantener tiempos de scraping eficientes
• 🛡️ Ética: Respetar términos de servicio de sitios web

📖 Código de Conducta

Este proyecto adhiere al Código de Conducta de Contributor Covenant. Al participar, te comprometes a mantener un ambiente acogedor y respetuoso.

---

📊 Datos Históricos

🔄 Migración a v3.0.0

Con la versión 3.0.0, hemos reestructurado completamente la arquitectura de datos para mejorar performance, calidad y análisis. Los datos históricos anteriores siguen disponibles:

📥 Descargas Históricas

Período	Versión	Registros	Enlace de Descarga
2023 Completo	v1.x	~30,000	📁 Descargar JSON
2024 Q1-Q3	v2.x	~45,000	📁 Descargar CSV
2024 Actual	v3.0.0	~75,000	📁 Datos Actuales

💡 Nota: Los datos históricos están pre-procesados y listos para usar. No requieren ETL adicional.

---

📄 Licencia

Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International

Este trabajo está licenciado bajo CC BY-NC-SA 4.0

⚖️ Términos de Uso Detallados

Tipo de Uso	Permitido	Condiciones
✅ Personal y Académico	✓ Libre	Atribución requerida
✅ Investigación	✓ Libre	Compartir bajo misma licencia
✅ Modificación	✓ Permitida	Documentar cambios
✅ Distribución	✓ Permitida	Misma licencia CC BY-NC-SA
❌ Comercial	❌ Requiere autorización	Contactar al mantenedor
📊 Datos Scrapeados	⚠️ Sujeto a términos originales	Verificar con fuentes

🤝 Solicitudes Comerciales

Para uso comercial, por favor contacta a @erik172 o envía un email detallando:

• Propósito comercial específico
• Volumen de datos requerido
• Duración del uso proyectado
• Beneficios para la comunidad (opcional)

---

👥 Equipo

🚀 Mantenedor Principal

Erik Garcia 🔧 CEO & CTO & Lead Developer 📊 ML Engineer

@erik172

🎯 Especialidades

• 🕷️ Web Scraping & Data Engineering
• 🤖 Machine Learning & Deep Learning
• 🏗️ System Architecture & Scalability

💝 Apoyo al Proyecto

Si este proyecto te resulta útil, considera apoyar su desarrollo:

🤝 Colaboradores

¡Este proyecto crece gracias a los colaboradores de la comunidad!

Ver todos los colaboradores →

---

🏢 Organizaciones

Parte del ecosistema Builker
Innovar. Impactar. Trascender. Forjamos el futuro con cada solución.

---

🌟 Star History

---

🏠 Hecho con ❤️ desde Bogotá, Colombia para el mundo 🌎

"Datos abiertos para ciudades inteligentes"