Documentación REST API

Resumen

Genere una clave API personal en la configuración de su cuenta. Luego use solicitudes HTTP GET estándar con su clave API para obtener puntuaciones de visibilidad, recuentos de menciones y datos de sentimiento de ChatGPT, Gemini, Perplexity y Claude. Funciona con Excel, Google Sheets, Power BI, Tableau, Python y cualquier otro cliente HTTP.

Índice

1. URL base
2. Autenticación
3. Acceso por solicitud (MPP)
4. Límites de velocidad
5. Endpoints
   1. GET /api/v1/looker/schema
   2. GET /api/v1/looker/data
   3. GET /api/v1/looker/selections
6. Referencia de campos de datos
7. Formato de respuesta
8. Manejo de errores
9. Ejemplos de código
10. Preguntas frecuentes

curl -H "Authorization: Bearer avt_your_key_here" \
  https://your-domain.com/api/v1/looker/data

# First request without credentials
curl -i https://your-domain.com/api/v1/looker/data

# HTTP/1.1 402 Payment Required
# WWW-Authenticate: Payment challenge="...", ...

# Reintentar con la credencial de pago
curl -H "Authorization: Payment <credential>" \
  https://your-domain.com/api/v1/looker/data

Devuelve el esquema de datos con nombres de campos, tipos e información semántica. Útil para comprender la estructura de datos antes de consultar.

Parámetros: Ninguno

Solicitud de ejemplo:

curl -H "Authorization: Bearer avt_your_key_here" \
  https://your-domain.com/api/v1/looker/schema

Respuesta de ejemplo:

{
  "schema": [
    {
      "name": "date",
      "label": "Date",
      "dataType": "STRING",
      "semantics": {
        "conceptType": "DIMENSION",
        "semanticType": "YEAR_MONTH_DAY"
      }
    },
    {
      "name": "visibility_score",
      "label": "Visibility Score",
      "dataType": "NUMBER",
      "semantics": {
        "conceptType": "METRIC"
      }
    }
  ]
}

Devuelve los resultados de su análisis de visibilidad AI. Soporta filtrado por fecha, área temática y sistema AI. Incluye paginación para grandes conjuntos de datos.

Parámetros de consulta:

Solicitud de ejemplo:

curl -H "Authorization: Bearer avt_your_key_here" \
  "https://your-domain.com/api/v1/looker/data?date_from=2025-01-01&date_to=2025-01-31&ai_system=chatgpt&limit=500"

Respuesta de ejemplo:

{
  "data": [
    {
      "date": "20250115",
      "topic_area": "Brand Monitoring",
      "prompt": "What is the best project management tool?",
      "category": "Product Comparison",
      "funnel_stage": "Consideration",
      "ai_system": "chatgpt",
      "brand": "Asana",
      "visibility_score": 75,
      "mention_count": 3,
      "position_score": 85,
      "sentiment_score": 0.8,
      "web_search_used": false
    }
  ],
  "pagination": {
    "total": 1250,
    "limit": 500,
    "offset": 0,
    "has_more": true
  }
}

Devuelve una lista de sus áreas temáticas (selecciones) con sus IDs. Use estos IDs para filtrar datos en el endpoint /data.

Parámetros: Ninguno

Solicitud de ejemplo:

curl -H "Authorization: Bearer avt_your_key_here" \
  https://your-domain.com/api/v1/looker/selections

Respuesta de ejemplo:

{
  "selections": [
    {
      "id": 42,
      "name": "Brand Monitoring",
      "description": "Track brand mentions across AI platforms",
      "prompt_count": 25,
      "is_active": true,
      "created_at": "2025-01-10T14:30:00"
    }
  ]
}

import requests

API_KEY = "avt_your_key_here"
BASE_URL = "https://your-domain.com/api/v1/looker"

headers = {"Authorization": f"Bearer {API_KEY}"}

# Obtener todas las áreas temáticas
selections = requests.get(f"{BASE_URL}/selections", headers=headers).json()
print(selections)

# Obtener datos de visibilidad para enero 2025
params = {
    "date_from": "2025-01-01",
    "date_to": "2025-01-31",
    "limit": 1000
}
data = requests.get(f"{BASE_URL}/data", headers=headers, params=params).json()
print(f"Total records: {data['pagination']['total']}")

# Paginar a través de todos los resultados
all_records = []
offset = 0
while True:
    params["offset"] = offset
    response = requests.get(f"{BASE_URL}/data", headers=headers, params=params).json()
    all_records.extend(response["data"])
    if not response["pagination"]["has_more"]:
        break
    offset += params["limit"]

print(f"Fetched {len(all_records)} records total")

const API_KEY = "avt_your_key_here";
const BASE_URL = "https://your-domain.com/api/v1/looker";

const headers = { "Authorization": `Bearer ${API_KEY}` };

// Obtener datos de visibilidad
const response = await fetch(`${BASE_URL}/data?date_from=2025-01-01&limit=500`, { headers });
const result = await response.json();
console.log(`Total: ${result.pagination.total} records`);

# Obtener esquema
curl -H "Authorization: Bearer avt_your_key_here" \
  https://your-domain.com/api/v1/looker/schema

# Obtener datos con filtros
curl -H "Authorization: Bearer avt_your_key_here" \
  "https://your-domain.com/api/v1/looker/data?date_from=2025-01-01&ai_system=chatgpt&limit=100"

# Obtener áreas temáticas
curl -H "Authorization: Bearer avt_your_key_here" \
  https://your-domain.com/api/v1/looker/selections

function getVisibilityData() {
  const API_KEY = "avt_your_key_here";
  const url = "https://your-domain.com/api/v1/looker/data?limit=500";

  const options = {
    headers: { "Authorization": "Bearer " + API_KEY },
    muteHttpExceptions: true
  };

  const response = UrlFetchApp.fetch(url, options);
  const json = JSON.parse(response.getContentText());

  // Escribir datos en la hoja activa
  const sheet = SpreadsheetApp.getActiveSheet();
  const headers = Object.keys(json.data[0]);
  sheet.getRange(1, 1, 1, headers.length).setValues([headers]);

  const rows = json.data.map(row => headers.map(h => row[h]));
  sheet.getRange(2, 1, rows.length, headers.length).setValues(rows);
}