API de Análisis Estructural de Sitios Web

El endpoint /api/site/analyze/structure permite realizar análisis estructurales de sitios web, evaluando la jerarquía de elementos, bloques de contenido, estructura semántica y relaciones entre elementos.

Características principales

Implementación avanzada y flexible
Enfocado específicamente en el análisis estructural del sitio
Utiliza servicios especializados para el análisis de estructura
Permite configurar múltiples opciones avanzadas
Puede utilizar diferentes proveedores de IA (OpenAI, Anthropic, Gemini)
Sistema sofisticado de manejo de errores
Posibilidad de guardar resultados en la base de datos

Analizador Estructural de Sitios Web

Prueba el API de análisis estructural de sitios web con tus propios parámetros.

Enfoque del análisis estructural

El análisis estructural se centra en comprender la organización y jerarquía del contenido del sitio web, incluyendo:

Jerarquía de elementos
Bloques de contenido
Estructura semántica
Relaciones entre elementos
Navegación y menús
Secciones principales y su importancia
Patrones de diseño utilizados

Métodos disponibles

POST /api/site/analyze/structure

Realiza un análisis estructural del sitio web, enfocado en la estructura del DOM y la organización del contenido.

Parámetros de solicitud


{
  "url": "https://ejemplo.com", // URL del sitio (obligatorio)
  "htmlContent": "<html>...</html>", // HTML de la página (opcional)
  "screenshot": "data:image/png;base64,...", // Captura de pantalla en Base64 (opcional)
  "site_id": "uuid-of-the-site", // ID del sitio para almacenamiento en BD (opcional)
  "user_id": "uuid-of-the-user", // ID del usuario para almacenamiento en BD (opcional)
  "options": {
    "timeout": 30000, // Tiempo máximo de espera en milisegundos (entre 5000 y 60000)
    "userAgent": "Mozilla/5.0...", // User Agent personalizado (opcional)
    "depth": 2, // Profundidad del análisis (1-3)
    "ignoreSSL": false, // Ignorar errores de certificados SSL
    "failOnError": false, // Si es false, intenta continuar incluso con errores
    "safeSelectors": true, // Si es true, valida los selectores antes de usarlos
    "includeScreenshot": true, // Incluir captura de pantalla en la respuesta
    "provider": "openai", // Proveedor de IA: 'openai', 'anthropic', 'gemini'
    "modelId": "gpt-5-nano", // Modelo específico de IA a utilizar
    "saveToDatabase": false // Guardar resultados en la base de datos (requiere site_id y user_id)
  }
}

Respuesta


{
  "url": "https://ejemplo.com",
  "structuredAnalysis": {
    // Detalles del análisis estructural...
  },
  "requestTime": 12345, // Tiempo de procesamiento en milisegundos
  "timestamp": "2023-06-15T14:30:00Z",
  "analysis_id": "uuid-of-saved-analysis", // Presente solo si saveToDatabase=true y hubo éxito
  "database_status": "success", // "success", "error", o "not_saved"
  "database_error": null // Mensaje de error si database_status es "error"
}

Respuesta detallada


{
  "url": "https://ejemplo.com",
  "structuredAnalysis": {
    "headings": {
      "h1": 1,
      "h2": 5,
      "h3": 12,
      "h4": 8
    },
    "sections": [
      {
        "type": "header",
        "elements": 5,
        "importance": "high"
      },
      {
        "type": "main-content",
        "elements": 25,
        "importance": "high"
      },
      {
        "type": "sidebar",
        "elements": 10,
        "importance": "medium"
      },
      {
        "type": "footer",
        "elements": 8,
        "importance": "low"
      }
    ],
    "navigation": {
      "mainMenu": {
        "items": 6,
        "depth": 2
      },
      "footer": {
        "items": 4,
        "depth": 1
      }
    },
    "contentBlocks": [
      {
        "type": "hero",
        "elements": 3,
        "position": "top"
      },
      {
        "type": "features",
        "elements": 12,
        "position": "middle"
      },
      {
        "type": "testimonials",
        "elements": 6,
        "position": "middle-bottom"
      },
      {
        "type": "contact",
        "elements": 5,
        "position": "bottom"
      }
    ],
    "semantics": {
      "articleCount": 3,
      "sectionCount": 8,
      "navCount": 2,
      "asideCount": 1,
      "footerCount": 1,
      "headerCount": 1
    },
    "accessibility": {
      "ariaUsage": {
        "score": 75,
        "details": "Uso moderado de atributos ARIA"
      },
      "semanticStructure": {
        "score": 85,
        "details": "Buena estructura semántica general"
      }
    }
  },
  "analysis": {
    "clarity": 85,
    "hierarchy": 90,
    "consistency": 80,
    "userExperience": 88,
    "navigationUsability": 82,
    "contentOrganization": 87
  },
  "patterns": [
    {
      "name": "Hero Section",
      "implementation": "Estándar",
      "effectiveness": "Alta"
    },
    {
      "name": "Card Grid",
      "implementation": "Responsive",
      "effectiveness": "Media-Alta"
    },
    {
      "name": "Sticky Navigation",
      "implementation": "Parcial",
      "effectiveness": "Media"
    }
  ],
  "recommendations": [
    {
      "category": "estructura",
      "priority": "media",
      "issue": "Jerarquía de encabezados inconsistente",
      "recommendation": "Asegurar que los encabezados sigan una jerarquía lógica",
      "impact": "Mejora en SEO y accesibilidad"
    },
    {
      "category": "navegación",
      "priority": "alta",
      "issue": "Menú móvil difícil de usar",
      "recommendation": "Simplificar la estructura del menú en dispositivos móviles",
      "impact": "Mejora significativa en la experiencia móvil"
    },
    {
      "category": "contenido",
      "priority": "baja",
      "issue": "Bloques de contenido desalineados",
      "recommendation": "Alinear los bloques de contenido para mejorar la coherencia visual",
      "impact": "Mejora estética y de usabilidad"
    }
    // Otras recomendaciones...
  ],
  "timestamp": "2023-06-15T14:30:00Z",
  "analyzedBy": "AI Site Structure Analyzer v1.0",
  "analysisVersion": "1.0.0",
  "processingTime": 8765,
  "errors": [
    {
      "code": "SELECTOR_ERROR",
      "message": "No se pudo analizar un selector",
      "details": ".complex-selector > div:nth-child(3)",
      "recoverable": true
    }
    // Otros errores no críticos...
  ],
  "completeness": 95 // Porcentaje de completitud del análisis (0-100)
}

GET /api/site/analyze/structure

Obtiene información sobre el servicio de análisis estructural.

Respuesta


{
  "service": "AI Site Structure Analyzer",
  "version": "1.0.0",
  "status": "operational",
  "capabilities": [
    "structure-analysis",
    "semantic-analysis",
    "navigation-analysis",
    "content-organization",
    "pattern-detection"
  ],
  "limits": {
    "requestsPerDay": 100,
    "maxTimeout": 60000
  }
}

Endpoints relacionados

GET /api/site/analysis/:id

Obtiene un análisis específico por su ID (requiere que el análisis se haya almacenado en la base de datos).

Respuesta


{
  "success": true,
  "analysis": {
    "id": "uuid-of-analysis",
    "site_id": "uuid-of-site",
    "url_path": "/path/analyzed",
    "structure": { /* Datos de análisis estructural */ },
    "user_id": "uuid-of-user",
    "created_at": "2023-06-15T14:30:00Z",
    "updated_at": "2023-06-15T14:35:00Z",
    "status": "completed",
    "request_time": 12345,
    "provider": "openai",
    "model_id": "gpt-5-nano"
  }
}

GET /api/site/analysis/site/:siteId

Obtiene todos los análisis para un sitio específico (requiere el parámetro user_id en la URL de consulta).

Respuesta


{
  "success": true,
  "analyses": [
    {
      "id": "uuid-of-analysis-1",
      "site_id": "uuid-of-site",
      "url_path": "/path/analyzed/1",
      "structure": { /* Datos de análisis estructural */ },
      "user_id": "uuid-of-user",
      "created_at": "2023-06-15T14:30:00Z",
      "updated_at": "2023-06-15T14:35:00Z",
      "status": "completed",
      "request_time": 12345,
      "provider": "openai",
      "model_id": "gpt-5-nano"
    },
    {
      "id": "uuid-of-analysis-2",
      "site_id": "uuid-of-site",
      "url_path": "/path/analyzed/2",
      // ... más propiedades
    }
  ]
}

Diferencias con la API General de Análisis

Esta API específica de análisis estructural (/api/site/analyze/structure) difiere de la API general (/api/site/analyze) en los siguientes aspectos:

Enfoque: Se centra exclusivamente en el análisis estructural del sitio, mientras que la API general abarca rendimiento, SEO, accesibilidad y mejores prácticas.
Parámetros: Incluye parámetros específicos para el análisis estructural, como la posibilidad de proporcionar HTML directamente.
Respuesta: Devuelve una estructura de respuesta enfocada en elementos estructurales como jerarquía, secciones, navegación y bloques de contenido.
Análisis: Proporciona un análisis más profundo de la estructura del sitio, incluyendo patrones de diseño y organización del contenido.
Almacenamiento: Permite guardar los resultados del análisis en la base de datos para su consulta posterior.

Nota: Si necesitas un análisis más completo que incluya rendimiento, SEO y otros aspectos, puedes utilizar la API general /api/site/analyze. Para más información, consulta la documentación de la API General de Análisis de Sitios.

Códigos de estado

200 OK: La solicitud se completó correctamente
400 Bad Request: Parámetros de solicitud inválidos
404 Not Found: El recurso solicitado no existe
429 Too Many Requests: Se ha excedido el límite de solicitudes
500 Internal Server Error: Error en el servidor durante el análisis
504 Gateway Timeout: Tiempo de espera agotado durante el análisis

Ejemplos de uso

Realizar un análisis estructural básico


const response = await fetch('https://tudominio.com/api/site/analyze/structure', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://ejemplo.com',
    options: {
      depth: 2,
      timeout: 30000,
      includeScreenshot: true
    }
  })
});
 
const data = await response.json();
console.log(data.structuredAnalysis); // Estructura del sitio

Realizar un análisis estructural con HTML proporcionado y guardar resultados


const response = await fetch('https://tudominio.com/api/site/analyze/structure', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://ejemplo.com',
    htmlContent: '<html>...</html>', // HTML del sitio
    site_id: 'uuid-del-sitio', // ID del sitio en tu BD
    user_id: 'uuid-del-usuario', // ID del usuario en tu BD
    options: {
      depth: 3,
      provider: 'anthropic',
      modelId: 'claude-3-5-sonnet-20240620',
      saveToDatabase: true // Guardar análisis en BD
    }
  })
});
 
const data = await response.json();
console.log(data.analysis_id); // ID del análisis guardado
console.log(data.structuredAnalysis); // Datos del análisis

Obtener un análisis guardado por su ID


const analysisId = 'uuid-del-analisis';
const response = await fetch(`https://tudominio.com/api/site/analysis/${analysisId}`, {
  method: 'GET'
});
 
const data = await response.json();
console.log(data.analysis); // Análisis recuperado

Obtener todos los análisis de un sitio


const siteId = 'uuid-del-sitio';
const userId = 'uuid-del-usuario';
const response = await fetch(`https://tudominio.com/api/site/analysis/site/${siteId}?user_id=${userId}`, {
  method: 'GET'
});
 
const data = await response.json();
console.log(data.analyses); // Lista de análisis

Almacenamiento en Base de Datos

Para utilizar la funcionalidad de almacenamiento en base de datos, se utiliza la tabla analysis existente en tu base de datos Supabase.

Requisitos previos

Proyecto Supabase con la tabla analysis ya configurada
Tabla analysis con los campos necesarios (ver documentación)

Configuración

No es necesario crear una nueva tabla. Esta API utiliza la tabla analysis que ya existe en el sistema. Solamente debes asegurarte que la tabla tenga los campos requeridos:

id (UUID, clave primaria)
site_id (UUID)
url_path (TEXT)
structure (JSONB)
user_id (UUID)
created_at (TIMESTAMPTZ)
updated_at (TIMESTAMPTZ)
status (TEXT)
request_time (INTEGER)
provider (TEXT)
model_id (TEXT)

Para más detalles sobre la configuración y solución de problemas, consulta la documentación en docs/setup-site-analysis-database.md.

Posibles errores

Si recibes un error al intentar guardar el análisis en la base de datos, el campo database_error en la respuesta proporcionará información sobre el problema:


{
  "url": "https://ejemplo.com",
  "structuredAnalysis": { /* datos del análisis */ },
  "database_status": "error",
  "database_error": "The analysis table does not exist. Please contact the administrator."
}

Los errores comunes incluyen:

Tabla inexistente: Verifica que la tabla analysis exista en tu base de datos
Permisos insuficientes: Verifica las políticas RLS y permisos
Valores inválidos: Asegúrate de que los UUIDs proporcionados sean válidos