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 de análisis impulsado por IA que te ayuda a consultar, analizar y diagnosticar tus datos de Google Analytics con lenguaje natural.

Si bien Pregúntale al Asesor 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 Pregúntale al Asesor de forma programática a través de HTTP.

Importante: Este producto utiliza IA y podría mostrar información inexacta. Tu actividad de chat se podrá usar para mejorar el producto, y el uso que hagas de este producto estará 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 hacer 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 (por ejemplo, "¿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 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 como true.

Autenticación

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

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 alcances necesarios, ejecuta lo siguiente:

    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 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 ChatRequest que contenga tu userQuery. Configura returnPropertyQuota como 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 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:

  • 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 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 preservar el contexto, incluye el sessionId que muestra la respuesta anterior en tu solicitud.

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

Como seguimiento de 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 respuesta y bloques de datos

El ChatResponse objeto muestra componentes estructurados en el blocks array:

Tipo de bloque 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 celdas)

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 de punto flotante numéricos

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 muestra en propertyQuota cuando returnPropertyQuota es true:

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

Aplicaciones de integración sugeridas

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

Chat empresarial y bots de colaboración

Conecta el espacio de trabajo de chat de tu 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.
  • Representación de tarjetas enriquecidas: Da formato a los tablebloques de respuesta interactivos en widgets de tarjetas interactivas.

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

Equipa 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 de lenguaje natural.
  • El agente recibe resúmenes de alta veracidad y tablas estructuradas para sintetizar 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 clave de rendimiento 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 CRM.

Próximos pasos