La méthode chat de l'API Data fournit un accès programmatique à Ask Advisor dans Google Analytics, un assistant analytique optimisé par l'IA qui vous aide à interroger, analyser et diagnostiquer vos données Google Analytics en langage naturel.
Bien qu'Ask Advisor soit disponible de manière interactive dans l'interface utilisateur de Google Analytics, l'API chat permet aux développeurs, aux agents IA autonomes et aux outils internes d'interagir avec Ask Advisor de manière programmatique via HTTP.
Important : Ce produit utilise l'IA et peut afficher des informations inexactes. Votre activité de chat peut être utilisée pour améliorer le produit, et votre utilisation est soumise aux Conditions d'utilisation, au Règlement sur l'utilisation de l'IA et aux Règles de confidentialité de Google.
Présentation
La méthode chat permet à la fois de poser des questions ponctuelles sur les données en un seul tour et d'effectuer des sessions de conversation multitours :
- Requêtes à un seul tour : posez des questions analytiques immédiates (par exemple, "Quels ont été nos principaux canaux de trafic la semaine dernière ?") et recevez des réponses en langage naturel ainsi que des tables de données structurées.
- Conversations multitours : transmettez un
sessionIdpour conserver l'historique des conversations et poser des questions de diagnostic complémentaires (par exemple, "Pourquoi le trafic généré par les résultats naturels a-t-il diminué au cours de cette période ?"). - Réponses de données structurées : en plus des récits textuels, les réponses contiennent des blocs
tablestructurés avec des en-têtes de colonne et des lignes. - Surveillance des quotas de chat : inspectez les quotas de jetons de chat restants par jour et par heure en définissant
returnPropertyQuotasurtrue.
Authentification
Les appels à la méthode chat nécessitent une autorisation OAuth 2.0 avec le champ d'application suivant :
Avant de commencer
Installez et initialisez gcloud CLI.
Pour générer des identifiants par défaut de l'application et accorder à votre compte les champs d'application nécessaires, exécutez la commande suivante :
gcloud auth application-default login --scopes="https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/analytics.chatbot.read"Dans l'interface utilisateur de Google Analytics, accordez à votre compte utilisateur l'accès à une propriété Google Analytics.
Configurez vos variables d'environnement en saisissant les informations suivantes. Remplacez
PROJECT_IDpar l'ID de votre projet etPROPERTY_IDpar l'ID de votre propriété Google Analytics.export PROJECT_ID=
PROJECT_IDexport PROPERTY_ID=PROPERTY_ID
Exemple 1 : Requête à un seul tour avec suivi des quotas
Pour démarrer une conversation, créez un ChatRequest contenant votre userQuery.
Définissez returnPropertyQuota sur true pour inspecter le solde de jetons restant.
Scénario : Revenus et taux de conversion par appareil
Vous souhaitez comparer les revenus et le taux de conversion des sessions sur différents appareils au cours des 30 derniers jours.
Requête 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
}'
Réponse HTTP
La réponse contient les éléments suivants :
- Un
sessionIdnouvellement attribué que vous pouvez utiliser pour les tours de suivi. - Liste de
blockscontenant à la fois un résumé en langage naturel (text) et un tableau structuré (table). Les blocs de texte peuvent contenir une mise en forme Markdown, comme du texte en gras, des titres et des liens. - Les détails de la propriété
propertyQuota.
{
"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
}
}
}
Exemple 2 : Diagnostic conversationnel multitour
Pour poser une question complémentaire tout en conservant le contexte, incluez le sessionId renvoyé par la réponse précédente dans votre requête.
Scénario : Comparer avec la période précédente
Pour faire suite à la comparaison d'appareils précédente, vous demandez à l'Advisor de comparer les résultats avec ceux de la période précédente.
Requête 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."
}'
Réponse HTTP
Ask Advisor utilise la mémoire de la session pour corréler les résultats avec la période précédente.
{
"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%"
}
]
}
}
}
]
}
Structure de la réponse et blocs de données
L'objet ChatResponse renvoie des composants structurés dans le tableau blocks :
| Type de bloc | Champ | Description |
|---|---|---|
| Texte narratif | blocks[].text |
Explication lisible par l'humain et conclusions analytiques de haut niveau. |
| Tableau structuré | blocks[].table |
Répartition des données tabulaires contenant headers (noms et types de données) et rows (valeurs des cellules). |
Types de données des en-têtes de table
Les colonnes de blocks[].table.headers décrivent le type de données sémantique :
string: valeurs textuelles catégorielles (par exemple,"desktop","/shop/apparel").float: nombres à virgule flottante numériques.
Gestion des quotas de chat
Les requêtes Ask Advisor consomment des jetons de chat en fonction de la complexité de la requête.
L'état actuel du quota est renvoyé dans propertyQuota lorsque returnPropertyQuota est défini sur true :
tokensPerDay: limite quotidienne de jetons et solde restant.tokensPerHour: limite de débit de la fenêtre glissante horaire et solde restant.
Applications d'intégration suggérées
La méthode properties.chat permet de débloquer plusieurs architectures d'intégration entre les équipes et les outils :
Bots de chat et de collaboration d'entreprise
Associez l'espace de travail de chat de votre équipe directement à Google Analytics.
- Sessions par fil de discussion : stockez l'
sessionIdavec l'ID du fil de discussion pour permettre aux membres de l'équipe de poser des questions complémentaires de manière collaborative. - Rendu de fiches enrichies : formatez les blocs de réponse
tableen widgets de fiches interactives.
Agents IA autonomes et outils MCP (Model Context Protocol)
Équipez les orchestrateurs de LLM (comme Gemini, LangChain ou Claude) d'un outil d'analyse GA :
- Plutôt que de forcer un LLM à générer des requêtes
runReportcomplexes, l'agent LLM peut appeler la méthodechatavec une intention en langage naturel. - L'agent reçoit des résumés très factuels et des tableaux structurés qu'il synthétise en recommandations marketing multicanal.
Briefings et alertes automatisés pour les équipes de direction
Créez des services programmés qui examinent les anomalies de manière proactive :
- Un job Cron quotidien envoie la requête suivante : "Résume les principales métriques de performances d'hier et identifie toute baisse anormale des conversions."
- Si une anomalie est détectée, le script déclenche automatiquement une requête de suivi pour diagnostiquer les causes principales et publie un résumé sur les tableaux de bord internes ou les systèmes CRM.
Étapes suivantes
- Essayez le notebook Colab Ask Advisor interactif pour exécuter des requêtes à un ou plusieurs tours à l'aide de la bibliothèque cliente Python.
- Consultez la documentation de référence de l'API REST
properties.chat. - En savoir plus sur les quotas et limites de l'API Data