API Geoptim v1

Intégrez Geoptim dans tus herramientas

Accede a los proyectos, puntuaciones y resultados de análisis IA de tus clientes directamente a través de nuestra API REST. Integra la visibilidad IA en tus dashboards, informes y flujos de trabajo.

Iniciar sesión Crear una cuenta

Documentación API

Integración simple, respuestas JSON estandarizadas

Autenticación

Añada su token en el encabezado Authorization de cada solicitud:

# Ejemplo cURL
curl -H "Authorization: Bearer ***token***" \
https://geoptim.ai/api/v1/projects.php
POST GET /api/v1/analyze.php - Lanzar un análisis de IA

POST para lanzar un análisis en un proyecto. GET para seguir su estado.

# Lanzar un análisis
POST /api/v1/analyze.php
Body: { "project_id": 42, "question_type": "general" }

# Seguir el estado
GET /api/v1/analyze.php?id=123
project_id * question_type: general|ecommerce|local|saas
GET /api/v1/scores.php - Puntuaciones y métricas

Puntuaciones de visibilidad IA, métricas detalladas e historial de evolución.

GET /api/v1/scores.php?project_id=42
GET /api/v1/scores.php?project_id=42&last=1
GET /api/v1/scores.php?scan_id=123
project_id scan_id last=1 límite
GET /api/v1/recommendations.php - Recomendaciones IA

Recomendaciones personalizadas generadas por IA, filtrables por prioridad y categoría.

GET /api/v1/recommendations.php?project_id=42
GET /api/v1/recommendations.php?scan_id=123&priority=critical
GET /api/v1/recommendations.php?scan_id=123&category=ai_visibility
project_id scan_id priority: critical|high|medium|low category: seo|content|technical|ai_visibility
GET /api/v1/projects.php - Lista todos tus proyectos

Parámetros opcionales: limit (máx 100), offset, status (active/paused/archived)

GET /api/v1/projects.php?limit=10&offset=0
GET /api/v1/projects.php?id=42
GET /api/v1/scans.php - Escaneos y resultados

Recupere los escaneos de un proyecto o todos los datos de un escaneo: panel GEO y panel SEO.

GET /api/v1/scans.php?project_id=42
GET /api/v1/scans.php?id=123
GET /api/v1/scans.php?audit_id=181
GET /api/v1/scans.php?id=123&include=seo_audit&seo_steps=step3_serp,step6_report
SecciónContenido
analysisAnálisis canónico: bloques técnico, rendimiento, contenido, confianza y sus pruebas
geoPreguntas, posiciones por IA, respuestas brutas de las IA, recomendaciones, query fan-out y SERPs asociadas
trustAnálisis de confianza y plataformas de opiniones
metricsMétricas medidas durante el escaneo
action_itemsAcciones recomendadas y su prioridad
seo_auditAuditoría SEO de la página: Lighthouse y Core Web Vitals, on-page, estructura de enlaces internos, palabras clave y posiciones, SERP, backlinks, E-E-A-T, brechas de contenido, informe
seo_domainEscaneo SEO del dominio: cartografía, rastreo, PageSpeed, palabras clave, mercado
metadataMetadatos brutos del pipeline (bajo demanda)
htmlHTML y Markdown capturados de la página (bajo demanda)
Parámetros: include (secciones a entregar, all para todo), exclude (secciones a eliminar), seo_steps (pasos de la auditoría SEO). Sin parámetro, todas las secciones excepto metadatos y html.
Posiciones de palabras clave: seo_audit.keyword_rankings proporciona para cada palabra clave la posición media retenida (position, rango en la página de Google) y cada valor observado (values). Un ensayo sin el sitio cuenta como la primera posición fuera del top 10 (counted_as).
GET /api/v1/competitors.php - Análisis competitivo

Compara tus proyectos con el benchmark global. Posicionamiento, percentil y deltas vs el promedio.

GET /api/v1/competitors.php
GET /api/v1/competitors.php?project_id=42
Retorna: puntuaciones, benchmark global, percentil, vs_benchmark, sus otros proyectos
GET POST /api/v1/webhooks.php - Webhooks y alertas

Configura webhooks para recibir notificaciones en tiempo real (escaneo completado, fallo, variación de puntuación).

# Listar webhooks
GET /api/v1/webhooks.php

# Crear un webhook
POST /api/v1/webhooks.php
Body: { "action": "create", "name": "Mi webhook", "url": "https://...", "events": ["scan.completed"] }

# Probar un webhook
POST /api/v1/webhooks.php
Body: { "action": "test", "webhook_id": 1 }
events: scan.completed | scan.failed | score.change
Firma HMAC-SHA256 en el encabezado X-Geoptim-Signature
POST GET /api/v1/reports.php - Informes automatizados

Genere reportes completos en formato JSON. Elija las secciones a incluir: puntuaciones, recomendaciones, historial, métricas.

# Generar un informe
POST /api/v1/reports.php
Body: {
  "project_id": 42,
  "format": "json",
  "include": ["scores", "recommendations", "history", "metrics"]
}

# Obtener un informe
GET /api/v1/reports.php?id=5

# Listar mis reportes
GET /api/v1/reports.php?list=1
secciones: puntuaciones | recomendaciones | historial | métricas | confianza
GET /api/v1/stats.php - Estadísticas globales

Vista sintética: número de proyectos, escaneos, puntuación promedio, proyectos principales y evolución.

GET /api/v1/stats.php

Formato de respuesta

{
  "success": true,
  "data": { ... },
  "meta": {
    "timestamp": "2026-02-03T12:00:00+01:00",
    "api_version": "v1",
    "usage": {
      "daily_used": 42,
      "daily_limit": 5000,
      "daily_remaining": 4958
    }
  }
}

Códigos HTTP

200
Éxito
401
No autenticado
429
Límite alcanzado
404
Recurso no encontrado