Demographics API Endpoints

🌐 URLs Base

Producción

https://nerdistan-datalake-production.up.railway.app

Desarrollo

http://localhost:8000

---

📊 Demographics Analytics (NUEVO)

Análisis Demográfico Completo

Proporciona análisis demográfico integral con insights de marketing.

GET /api/v2/cdp/analytics/demographics
GET /api/cdp/v2/analytics/demographics  # Alias para compatibilidad

Parámetros de Query

• tenant_id (required): ID del tenant a analizar

Ejemplo de Request

curl "https://nerdistan-datalake-production.up.railway.app/api/v2/cdp/analytics/demographics?tenant_id=22"

Response (200 OK)

{
  "success": true,
  "data": {
    "summary": {
      "total_customers": 4671,
      "customers_with_age": 845,
      "customers_with_gender": 4548,
      "customers_with_location": 4671,
      "overall_avg_age": 32.3,
      "completion_rates": {
        "age": 18.09,
        "gender": 97.37,
        "location": 100.0
      }
    },
    "age_analysis": [
      {
        "age_segment": "25-34",
        "generation": "Millennials",
        "customer_count": 233,
        "avg_age": 32.0,
        "avg_spent": 12514.88,
        "avg_orders": 0.1,
        "high_value_customers": 2,
        "male_count": 117,
        "female_count": 113,
        "percentage": 27.57
      }
    ],
    "gender_analysis": [
      {
        "gender_label": "Masculino",
        "gender_code": "M",
        "customer_count": 2330,
        "avg_spent": 331317.94,
        "avg_orders": 1.2,
        "avg_age": 32.0,
        "champions": 157,
        "millennials_core": 224,
        "percentage": 49.88
      }
    ],
    "geographic_analysis": [
      {
        "province": "Buenos Aires",
        "region": "Región Metropolitana",
        "customer_count": 4671,
        "avg_spent": 280616.68,
        "avg_orders": 1.2,
        "avg_age": 32.3,
        "male_count": 2330,
        "female_count": 2218,
        "percentage": 100.0
      }
    ],
    "cross_demographic": [
      {
        "age_segment": "25-34",
        "gender": "Masculino",
        "region": "Región Metropolitana",
        "customer_count": 224,
        "avg_spent": 12514.88,
        "avg_orders": 0.1
      }
    ],
    "marketing_segments": [
      {
        "facebook_age_range": "25_34",
        "google_age_range": "25-34",
        "gender": "M",
        "targetable_customers": 224,
        "avg_spent": 12514.88,
        "high_value": 2
      }
    ],
    "timestamp": "2025-09-21T21:31:46.805295"
  }
}

Casos de Uso

• Dashboard demográfico completo
• Análisis de audiencias para marketing
• Segmentación por edad y género
• Insights geográficos de ventas
• Preparación de segmentos para Facebook/Google Ads

---

👥 Customers Endpoint (ENRIQUECIDO)

Lista de Clientes con Datos Demográficos

El endpoint existente de clientes ahora incluye campos demográficos enriquecidos.

GET /api/cdp/v2/customers

Parámetros de Query

• tenant_id (required): ID del tenant
• limit (optional): Número de resultados (default: 50)
• offset (optional): Offset para paginación (default: 0)

Ejemplo de Request

curl "https://nerdistan-datalake-production.up.railway.app/api/cdp/v2/customers?tenant_id=22&limit=5"

Response con Campos Demográficos

{
  "success": true,
  "data": {
    "customers": [
      {
        "profile_id": "uuid-1234",
        "email": "customer@email.com",
        "first_name": "Juan",
        "last_name": "Pérez",

        // CAMPOS DEMOGRÁFICOS NUEVOS:
        "estimated_age": 32,
        "inferred_gender": "M",
        "age_segment": "25-34",
        "generation": "Millennials",
        "facebook_age_range": "25_34",
        "google_age_range": "25-34",
        "corrected_city": "Buenos Aires",
        "corrected_province": "Buenos Aires",
        "corrected_postal_code": "1000",
        "region": "Región Metropolitana",
        "location_confidence": 0.3,
        "location_correction_needed": true,
        "is_location_validated": false,

        // Campos existentes:
        "rfm_segment": "Champions",
        "historical_value": 58999764.0,
        "order_count": 19,
        "created_at": "2023-01-15T10:00:00Z",
        "last_order_date": "2024-09-15T14:30:00Z"
      }
    ],
    "pagination": {
      "total": 4671,
      "limit": 5,
      "offset": 0,
      "has_next": true
    }
  }
}

Nuevos Campos Demográficos

Campo	Tipo	Descripción
estimated_age	int	Edad calculada desde DNI
inferred_gender	string	M, F, U, o null
age_segment	string	Rango de edad (18-24, 25-34, etc.)
generation	string	Generación (Gen Z, Millennials, etc.)
facebook_age_range	string	Formato Facebook Ads
google_age_range	string	Formato Google Ads
corrected_city	string	Ciudad corregida
corrected_province	string	Provincia corregida
region	string	Región geográfica
location_confidence	float	Confianza de ubicación (0-1)

---

📈 RFM Analytics (ENRIQUECIDO)

Análisis RFM con Insights Demográficos

El endpoint RFM existente ahora incluye breakdowns demográficos por segmento.

GET /api/v2/cdp/analytics/rfm

Parámetros de Query

• tenant_id (required): ID del tenant
• segment (optional): Filtrar por segmento específico

Response Enriquecida

{
  "success": true,
  "data": {
    "overview": {
      "total_customers": 4671,
      "avg_recency": 0,
      "avg_frequency": 0.32,
      "avg_monetary": 0.33,

      // NUEVOS INSIGHTS DEMOGRÁFICOS:
      "demographics": {
        "customers_with_age": 845,
        "avg_age": 32.3,
        "male_customers": 2330,
        "female_customers": 2218,
        "customers_with_location": 4671,
        "completion_rates": {
          "age": 18.09,
          "gender": 97.37,
          "location": 100.0
        }
      }
    },
    "distribution": [
      {
        "segment": "Champions",
        "customer_count": 307,
        "percentage": 6.57,
        "avg_recency": 30,
        "avg_frequency": 5.2,
        "avg_monetary": 8500.00,

        // BREAKDOWN DEMOGRÁFICO POR SEGMENTO:
        "demographics": {
          "avg_age": 33.2,
          "male_count": 157,
          "female_count": 140,
          "top_provinces": ["Buenos Aires"],
          "age_segments": {
            "18-24": 15,
            "25-34": 120,
            "35-44": 95,
            "45-54": 45,
            "55+": 32
          },
          "generations": {
            "Gen Z": 15,
            "Millennials": 215,
            "Gen X": 77
          }
        }
      }
    ]
  }
}

---

🎯 Filtros y Parámetros Avanzados

Filtros Disponibles (Próximamente)

Los siguientes filtros se implementarán en versiones futuras:

GET /api/v2/cdp/analytics/demographics?tenant_id=22&age_segment=25-34&gender=M&region=Metropolitana

Parámetros de Filtro Planificados

• age_segment: 18-24, 25-34, 35-44, 45-54, 55+
• gender: M, F, U
• region: Metropolitana, Centro, Cuyo, Norte, Patagonia
• generation: Gen Z, Millennials, Gen X, Boomers

---

📊 Estructura de Datos Demográficos

Segmentos de Edad

{
  "18-24": "Generación Z",
  "25-34": "Millennials/Gen Z",
  "35-44": "Millennials",
  "45-54": "Generación X",
  "55+": "Baby Boomers"
}

Códigos de Género

{
  "M": "Masculino",
  "F": "Femenino",
  "U": "Unisex/Otro",
  null: "Sin datos"
}

Regiones Geográficas

{
  "Región Metropolitana": ["Buenos Aires", "CABA"],
  "Región Centro": ["Córdoba", "Santa Fe", "Entre Ríos"],
  "Región Cuyo": ["Mendoza", "San Juan", "San Luis"],
  "Región Norte": ["Salta", "Tucumán", "Jujuy", "Santiago del Estero"],
  "Región Patagonia": ["Neuquén", "Río Negro", "Chubut", "Santa Cruz"]
}

Formatos de Marketing

{
  "facebook_formats": {
    "18-24": "18_24",
    "25-34": "25_34",
    "35-44": "35_44",
    "45-54": "45_54",
    "55+": "55_plus"
  },
  "google_formats": {
    "18-24": "18-24",
    "25-34": "25-34",
    "35-44": "35-44",
    "45-54": "45-54",
    "55-64": "55-64",
    "65+": "65+"
  }
}

---

⚡ Performance y Optimización

Tiempos de Respuesta Esperados

• Demographics endpoint: ~2-3 segundos
• Customers enriquecido: ~1-2 segundos (con paginación)
• RFM con demografía: ~2-3 segundos

Optimizaciones Implementadas

• Índices en campos demográficos clave
• Agregaciones pre-calculadas en tablas CDP
• Paginación automática en listas grandes
• Cache de resultados por 15 minutos

Límites de Rate

• Producción: 1000 requests per 15 minutos por IP
• Desarrollo: 10000 requests per 15 minutos por IP

---

🐛 Manejo de Errores

Errores Específicos de Demographics

400 Bad Request - Tenant Inválido

{
  "success": false,
  "error": "Invalid tenant_id",
  "details": "Tenant 999 not found or has no demographic data"
}

204 No Content - Sin Datos

{
  "success": true,
  "message": "No demographic data available for this tenant",
  "data": {
    "summary": {
      "total_customers": 0,
      "customers_with_age": 0,
      "customers_with_gender": 0,
      "customers_with_location": 0
    }
  }
}

422 Unprocessable Entity - Filtros Inválidos

{
  "success": false,
  "error": "Invalid filter parameters",
  "details": "age_segment must be one of: 18-24, 25-34, 35-44, 45-54, 55+"
}

---

🔗 Ejemplos de Integración

React Hook para Demographics

import { useState, useEffect } from 'react';

export const useDemographics = (tenantId) => {
  const [data, setData] = useState(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    const fetchDemographics = async () => {
      try {
        setLoading(true);
        const response = await fetch(
          `https://nerdistan-datalake-production.up.railway.app/api/v2/cdp/analytics/demographics?tenant_id=${tenantId}`
        );
        const result = await response.json();
        setData(result.data);
      } catch (err) {
        setError(err.message);
      } finally {
        setLoading(false);
      }
    };

    if (tenantId) {
      fetchDemographics();
    }
  }, [tenantId]);

  return { data, loading, error };
};

Python para Data Analysis

import requests
import pandas as pd

def get_demographic_analysis(tenant_id):
    """Obtiene análisis demográfico completo"""
    url = f"https://nerdistan-datalake-production.up.railway.app/api/v2/cdp/analytics/demographics"
    params = {"tenant_id": tenant_id}

    response = requests.get(url, params=params)
    data = response.json()

    if data["success"]:
        # Convertir a DataFrames para análisis
        age_df = pd.DataFrame(data["data"]["age_analysis"])
        gender_df = pd.DataFrame(data["data"]["gender_analysis"])
        geo_df = pd.DataFrame(data["data"]["geographic_analysis"])

        return age_df, gender_df, geo_df
    else:
        raise Exception(f"Error: {data.get('error', 'Unknown error')}")

# Ejemplo de uso
age_data, gender_data, geo_data = get_demographic_analysis(22)
print(f"Segmentos de edad: {len(age_data)}")
print(f"Análisis de género: {len(gender_data)}")

---

🚀 Roadmap de Features

Próximas Implementaciones

• Filtros avanzados por demografía
• Exportación de segmentos a CSV/Excel
• Webhooks para cambios demográficos
• Comparación histórica de demografía
• Predicción demográfica con ML
• Integración directa con Facebook/Google Ads

Mejoras Planificadas

• Cache inteligente por tenant
• Compresión de respuestas grandes
• Streaming de datos en tiempo real
• SDK específico para demographics

---

📋 Testing de Endpoints

Tenant 22 (Datos de Ejemplo)

# Test completo de demographics
curl "https://nerdistan-datalake-production.up.railway.app/api/v2/cdp/analytics/demographics?tenant_id=22" | jq '.'

# Test de customers con demografía
curl "https://nerdistan-datalake-production.up.railway.app/api/cdp/v2/customers?tenant_id=22&limit=3" | jq '.data.customers[0]'

# Test de RFM con insights demográficos
curl "https://nerdistan-datalake-production.up.railway.app/api/v2/cdp/analytics/rfm?tenant_id=22" | jq '.data.overview.demographics'

Scripts de Validación

#!/bin/bash
# validate_demographics.sh

TENANT_ID=22
BASE_URL="https://nerdistan-datalake-production.up.railway.app"

echo "Testing Demographics API..."

# Test 1: Demographics endpoint
echo "1. Testing demographics endpoint..."
curl -s "${BASE_URL}/api/v2/cdp/analytics/demographics?tenant_id=${TENANT_ID}" | jq '.success'

# Test 2: Customers with demographics
echo "2. Testing customers with demographics..."
curl -s "${BASE_URL}/api/cdp/v2/customers?tenant_id=${TENANT_ID}&limit=1" | jq '.data.customers[0].estimated_age'

# Test 3: RFM with demographics
echo "3. Testing RFM with demographics..."
curl -s "${BASE_URL}/api/v2/cdp/analytics/rfm?tenant_id=${TENANT_ID}" | jq '.data.overview.demographics.avg_age'

echo "Validation complete!"

---

Documentación: ✅ Completa Endpoints: ✅ Activos en producción Testing: ✅ Validado con Tenant 22 Última actualización: 21 de Septiembre 2025