Cómo usar el Asesor de Analytics para consultar y analizar tus datos

El método chat de la API de datos proporciona acceso programático a Analytics Advisor, un asistente analítico potenciado por IA que te ayuda a consultar, analizar y diagnosticar tus datos de Google Analytics con lenguaje natural.

Si bien el Asesor de Analytics está disponible de forma interactiva en la interfaz de usuario de Google Analytics, la API de chat permite que los desarrolladores, los agentes autónomos de IA y las herramientas internas interactúen con el Asesor de Analytics de forma programática a través de HTTP.

Importante: Este producto usa IA y puede mostrar información inexacta. Es posible que tu actividad de chat se use para mejorar el producto. El uso está sujeto a las Condiciones, la Política de Uso de IA y la Política de Privacidad de Google.

Descripción general

El método chat permite realizar preguntas de datos ad hoc de un solo turno y sesiones conversacionales de varios turnos:

  1. Consultas de un solo turno: Haz preguntas analíticas inmediatas (como "¿Cuáles fueron nuestros principales canales de tráfico la semana pasada?") y recibe respuestas en lenguaje natural junto con tablas de datos estructurados.
  2. Conversaciones de varios turnos: Pasa un sessionId para mantener el historial de conversaciones y hacer preguntas de seguimiento de diagnóstico (por ejemplo, "¿Por qué disminuyó el tráfico orgánico en ese período?").
  3. Respuestas de datos estructurados: Además de las narrativas de texto, las respuestas contienen bloques estructurados table con encabezados de columna y filas.
  4. Supervisión de la cuota de chat: Inspecciona las cuotas de tokens de chat restantes por día y por hora configurando returnPropertyQuota en true.

Autenticación

Las llamadas al método chat requieren autorización de OAuth 2.0 con el siguiente permiso:

Antes de comenzar

  1. Instala e inicializa la CLI de gcloud.

  2. Para generar credenciales predeterminadas de la aplicación y otorgar a tu cuenta los permisos necesarios, ejecuta el siguiente comando:

    gcloud auth application-default login --scopes="https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/analytics.chatbot.read"

  3. En la IU de Google Analytics, otorga a tu cuenta de usuario acceso a una propiedad de Google Analytics.

  4. Ingresa lo siguiente para configurar tus variables de entorno. Reemplaza PROJECT_ID por el ID de tu proyecto de y PROPERTY_ID por el ID de tu propiedad de Google Analytics. 

      export PROJECT_ID=PROJECT_ID
  export PROPERTY_ID=PROPERTY_ID

Ejemplo 1: Consulta de un solo turno con seguimiento de cuotas

Para iniciar una conversación nueva, crea un objeto ChatRequest que contenga tu userQuery. Establece returnPropertyQuota en true para inspeccionar tu saldo de tokens restante.

Situación: Ingresos y porcentaje de conversiones por dispositivo

Quieres comparar los ingresos y el porcentaje de sesiones con conversiones en diferentes dispositivos durante los últimos 30 días.

Solicitud HTTP

curl -X POST \
  "https://analyticsdata.googleapis.com/v1alpha/properties/${PROPERTY_ID}:chat" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "userQuery": "Compare our revenue and conversion rate across mobile vs desktop over the last 30 days.",
    "returnPropertyQuota": true
  }'

Respuesta HTTP

La respuesta contiene lo siguiente:

  • Es un sessionId recién asignado que puedes usar para turnos de seguimiento.
  • Es una lista de blocks que contiene un resumen en lenguaje natural (text) y una tabla estructurada (table). Los bloques de texto pueden contener formato de Markdown, como texto en negrita, encabezados y vínculos.
  • Son los detalles de propertyQuota de la propiedad.
{
  "sessionId": "692e9ab9-b338-4426-b006-a05f21ac7cd6",
  "blocks": [
    {
      "text": "Your report on revenue and conversion rates for mobile vs. desktop over the last 30 days (August 15 - September 13, 2026) is ready.\n\nHere is a summary of your revenue and conversion rate by device category:\n"
    },
   {
      "table": {
        "headers": [
          {
            "header": "Device Category",
            "dataType": "string"
          },
          {
            "header": "Total Revenue",
            "dataType": "string"
          },
          {
            "header": "User Conversion Rate",
            "dataType": "string"
          }
        ],
        "rows": [
          {
            "columns": [
              {
                "value": "Desktop"
              },
              {
                "value": "$17,412.62"
              },
              {
                "value": "99.9%"
              }
            ]
          },
          {
            "columns": [
              {
                "value": "Mobile"
              },
              {
                "value": "$15,309.41"
              },
              {
                "value": "99.46%"
              }
            ]
          }
      }
    },
    {
      "text": "**Revenue and Conversion Rate Trends:**\n\nRevenue from desktop devices saw a peak on August 18th, while mobile revenue peaked on August 30th. Conversion rates remained high and relatively stable for both desktop and mobile throughout the period."
    },
    {
      "text": "This product uses AI and may display inaccurate info. Your chat activity may be used to improve the product and your use is subject to Google's [Terms](https://policies.google.com/terms), [AI Use Policy](https://policies.google.com/terms/generative-ai/use-policy), and [Privacy Policy](https://policies.google.com/privacy). [Learn more about Chat AI Privacy](https://support.google.com/helpguide/answer/14185196)."
    }
  ],
   "propertyQuota": {
    "tokensPerDay": {
      "consumed": 26849,
      "remaining": 3723151
    },
    "tokensPerHour": {
      "consumed": 26849,
      "remaining": 473151
    }
  }
}

Ejemplo 2: Diagnóstico conversacional de varios turnos

Para hacer una pregunta de seguimiento y conservar el contexto, incluye el sessionId que devolvió la respuesta anterior en tu solicitud.

Situación: Comparación con el período anterior

Después de la comparación anterior de dispositivos, le pides al asesor que compare los resultados con el período anterior.

Solicitud HTTP

curl -X POST \
  "https://analyticsdata.googleapis.com/v1alpha/properties/${PROPERTY_ID}:chat" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "692e9ab9-b338-4426-b006-a05f21ac7cd6",
    "userQuery": "Compare results with the same period in the previous mounth."
  }'

Respuesta HTTP

El Asesor de Analytics usa la memoria de la sesión para correlacionar los resultados con el período anterior.

{
  "sessionId": "eb3284b2-49ce-4aed-b6d0-fdc15cb87b5f",
  "blocks": [
    {
      "text": "The following table provides a detailed comparison of total revenue and user conversion rate by device category for the two periods.\n"
    },
    {
      "table": {
        "headers": [
          {
            "header": "Device Category",
            "dataType": "string"
          },
          {
            "header": "Metric",
            "dataType": "string"
          },
          {
            "header": "Jul 16 - Aug 15, 2026",
            "dataType": "string"
          },
          {
            "header": "Aug 16 - Sep 14, 2026",
            "dataType": "string"
          }
        ],
        "rows": [
          {
            "columns": [
              {
                "value": "Desktop"
              },
              {
                "value": "Total Revenue"
              },
              {
                "value": "$17,412.62"
              },
              {
                "value": "$19,565.46"
              }
            ]
          },
          {
            "columns": [
              {
                "value": "Desktop"
              },
              {
                "value": "User Conversion Rate"
              },
              {
                "value": "1.90%"
              },
              {
                "value": "1.95%"
              }
            ]
          },
          {
            "columns": [
              {
                "value": "Mobile"
              },
              {
                "value": "Total Revenue"
              },
              {
                "value": "$13,997.19"
              },
              {
                "value": "$15,309.41"
              }
            ]
          },
          {
            "columns": [
              {
                "value": "Mobile"
              },
              {
                "value": "User Conversion Rate"
              },
              {
                "value": "1.95%"
              },
              {
                "value": "1.99%"
              }
            ]
          }
      }
    }
  ]
}

Estructura de respuesta y bloques de datos

El objeto ChatResponse devuelve componentes estructurados en el array blocks:

Tipo de bloqueo Campo Descripción
Texto narrativo blocks[].text Explicación legible y conclusiones analíticas de alto nivel.
Tabla estructurada blocks[].table Desglose de datos tabulares que contiene headers (nombres y tipos de datos) y rows (valores de celdas).

Tipos de datos de encabezados de tablas

Las columnas de blocks[].table.headers describen el tipo de datos semántico:

  • string: Son valores de texto categóricos (p.ej., "desktop", "/shop/apparel").
  • float: Números de punto flotante numéricos.

Administración de la cuota de chat

Las solicitudes del Asesor de Analytics consumen tokens de chat según la complejidad de la consulta. El estado actual de la cuota se devuelve en propertyQuota cuando returnPropertyQuota es true:

  • tokensPerDay: Límite de tokens diarios y saldo restante.
  • tokensPerHour: Límite de frecuencia de la ventana deslizante por hora y saldo restante.

Aplicaciones de integración sugeridas

El método properties.chat desbloquea varias arquitecturas de integración en equipos y herramientas:

Bots de chat y colaboración empresariales

Conecta tu espacio de trabajo de chat en equipo directamente a Google Analytics.

  • Sesiones encadenadas: Almacena el sessionId en el ID del hilo de chat para permitir que los miembros del equipo hagan preguntas de seguimiento de forma colaborativa.
  • Renderización de tarjetas enriquecidas: Da formato a los bloques de respuesta table en widgets de tarjetas interactivas.

Agentes autónomos de IA y herramientas del Protocolo de contexto del modelo (MCP)

Equipa a los organizadores de LLM (como Gemini, LangChain o Claude) con una herramienta de análisis de GA:

  • En lugar de obligar a un LLM a generar consultas runReport complejas, el agente de LLM puede invocar el método chat con una intención en lenguaje natural.
  • El agente recibe resúmenes de alta facticidad y tablas estructuradas para sintetizar recomendaciones de marketing multicanal.

Resúmenes ejecutivos y alertas automatizados

Crea servicios programados que investiguen anomalías de forma proactiva:

  • Un trabajo cron diario consulta: "Resume las métricas de rendimiento clave de ayer y detecta cualquier disminución anómala en las conversiones".
  • Si se encuentra una anomalía, la secuencia de comandos activa automáticamente una consulta de seguimiento para diagnosticar las causas raíz y publica un resumen en los paneles internos o los sistemas de CRM.