Usar Ask Advisor en Google Analytics de forma programática para consultar y analizar tus datos

El método chat de la API de datos proporciona acceso programático a Ask Advisor en Google Analytics, 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 Ask Advisor está disponible de forma interactiva en la interfaz de usuario de Google Analytics, la API de chat permite que los desarrolladores, los agentes de IA autónomos y las herramientas internas interactúen con Ask Advisor 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 y que tu uso esté sujeto a las Condiciones, la Política de Uso de la 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 de conversación 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 diagnóstico de seguimiento (como "¿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 de table estructurados 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 gcloud CLI.

  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 las 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 cuota

Para iniciar una conversación nueva, crea un ChatRequest que contenga tu userQuery. Establece returnPropertyQuota en true para inspeccionar el 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 todos los 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:

  • Un sessionId recién asignado que puedes usar para los turnos de seguimiento.
  • 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.
  • 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

Para continuar con la comparación de dispositivos anterior, 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

Ask Advisor 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 la 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 por humanos 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 celda).

Tipos de datos de encabezado de tabla

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

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

Administración de cuotas de Chat

Las solicitudes de Ask Advisor 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: Es el límite diario de tokens y el saldo restante.
  • tokensPerHour: Es el límite de frecuencia de la ventana variable por hora y el 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 para empresas

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

  • Sesiones en hilos: 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: Aplica formato a los bloques de respuesta table en widgets de tarjetas interactivas.

Agentes de IA autónomos 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 forzar a un LLM a generar consultas complejas de runReport, el agente de LLM puede invocar el método chat con un intent de lenguaje natural.
  • El agente recibe resúmenes de alta veracidad y tablas estructuradas para sintetizarlos en recomendaciones de marketing multicanal.

Informes 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 caída 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.

Próximos pasos