Construire un pipeline GeoX avec l’API Google Ads et les données du CRM

Le pipeline GeoX doit extraire les dépenses Google Ads par date et unité géographique, puis les relier aux résultats bruts du CRM, du point de vente ou d’une base commerciale interne. Google sépare explicitement ces deux familles de données : l’API fournit le coût, tandis que le système métier fournit les conversions ou revenus non filtrés et non attribués. Un rapport de conversions attribuées dans Google Ads ne remplace donc pas le fichier de résultats attendu.

Google documente GoogleAdsService avec Search ou SearchStream. La structure d’extraction comprend campaign.id, segments.date, le segment géographique correspondant à la granularité GeoX et metrics.cost_micros. geographic_view décrit la zone où l’utilisateur était présent ou pour laquelle il a montré un intérêt. location_view décrit les performances selon les zones ciblées par la campagne.

Chez CreatikLab, la règle opérationnelle consiste à suspendre l’analyse si une ligne ne peut plus être reliée à sa campagne, sa date, son unité géographique, sa source et sa transformation. Cette exigence relève de notre méthode de contrôle ; elle ne constitue pas une promesse de résultat publicitaire.

Les résultats issus des systèmes internes doivent être agrégés au jour et associés aux unités géographiques exactes du test. Google demande des valeurs absolues non négatives, par exemple un revenu brut ou un nombre total de conversions. Si le CRM calcule un revenu net avec des remboursements négatifs, la consigne est d’utiliser les montants bruts pour l’expérience et d’appliquer le taux de remboursement ultérieurement.

• Dépenses : identifiant de campagne, date, unité géographique du test et coût brut en micros.
• Résultats : date, même unité géographique et total métier non attribué.
• Référentiel géographique : nom de ressource Google, nom canonique, code interne et cellule du test.
• Transformation : conservation du coût brut et division par 1 000 000 pour la valeur monétaire.
• Étude multicellule : mesures de dépenses séparées pour chaque groupe expérimental.

Les vues de reporting ne renvoient pas simplement des noms de lieux. Les segments tels que segments.geo_target_city ou segments.geo_target_country renvoient un nom de ressource GeoTargetConstant. Google autorise la récupération du nom canonique par une requête geo_target_constant ou un rapprochement local avec son fichier CSV statique des cibles géographiques.

La vue ne doit pas être choisie après comparaison des totaux. Elle découle de la question expérimentale. geographic_view convient si l’unité représente la géographie de l’utilisateur ou son intérêt géographique. location_view convient si l’analyse doit suivre les zones ciblées dans les paramètres de campagne.

1. Décrire l’unité expérimentale sans vocabulaire API.
2. Préciser si elle représente l’utilisateur ou le ciblage de campagne.
3. Associer cette définition à la vue correspondante.
4. Contrôler quelques campagnes et zones connues dans l’extraction.
5. Faire approuver le choix avant l’automatisation et l’historisation.

La règle de décision CreatikLab est de rédiger une phrase testable avant la requête. Si les équipes média, data et métier ne donnent pas le même sens à cette phrase, la bonne action n’est pas de lancer le pipeline plus vite, mais de résoudre l’ambiguïté.

Une implémentation durable sépare l’extraction, le mapping géographique, la transformation monétaire, l’import CRM, la jointure et le rapprochement. Chaque étape produit une sortie intermédiaire versionnée. Il devient alors possible d’isoler un identifiant inconnu, une date déformée ou une différence entre les totaux source et destination.

1. Interroger GoogleAdsService avec Search ou SearchStream et archiver la réponse brute.
2. Extraire la campagne, la date, le segment géographique approuvé et metrics.cost_micros.
3. Résoudre chaque ressource vers son GeoTargetConstant, son nom canonique et son unité interne.
4. Créer une table de coûts convertis tout en conservant le champ brut en micros.
5. Extraire du CRM, de la caisse ou de la base de ventes les résultats quotidiens bruts sans filtre d’attribution Google Ads.
6. Vérifier que les unités métier correspondent exactement aux unités du plan GeoX.
7. Joindre sur les clés de date et de géographie approuvées sans supprimer les lignes non appariées.
8. Rapprocher les totaux par campagne, jour, zone et cellule avant toute analyse.

Une ligne non appariée peut signaler une couverture CRM incomplète, une ressource géographique non résolue ou une dépense hors cellule. Google ne fixe aucun taux universel d’appariement dans cette documentation. Le seuil d’acceptation doit donc être défini par le projet, documenté et approuvé.

Cette matrice permet de comparer un pipeline réel à un pipeline simplement déclaré fonctionnel.

• Grain de requête — Preuve : champs sélectionnés et export test. Risque : impossibilité de regrouper par unité GeoX. Action : corriger avant le chargement historique. Responsable : ingénieur analytics.
• Référentiel — Preuve : table de correspondance vers les noms canoniques. Risque : mélange des codes ISO, Nielsen et Google. Action : instaurer un dictionnaire contrôlé. Responsable : ingénieur data.
• Coût — Preuve : colonnes micros et monnaie. Risque : montants multipliés ou arrondis trop tôt. Action : appliquer le diviseur officiel et rapprocher. Responsable : analyste.
• Provenance métier — Preuve : spécification d’extraction CRM. Risque : utilisation de conversions attribuées. Action : produire les totaux bruts. Responsable : Revenue Operations.
• Dates — Preuve : profil quotidien des sources. Risque : formats modifiés ou journées décalées. Action : préserver YYYY-MM-DD. Responsable : propriétaire des données.
• Cellules — Preuve : dépenses séparées par groupe. Risque : agrégation prématurée. Action : restaurer le détail. Responsable : pilote de l’expérience.
• Gouvernance — Preuve : spécification approuvée et journal d’exceptions. Risque : changement silencieux. Action : bloquer la diffusion. Responsable : référent mesure.

Google renvoie segments.date au format YYYY-MM-DD et avertit que certains tableurs peuvent modifier automatiquement les dates. La documentation conseille un premier chargement dans Google Sheets afin de vérifier la lecture de la période. Dans un pipeline industrialisé, l’équivalent consiste à imposer un type explicite, contrôler le format et refuser les valeurs transformées avant l’agrégation.

Les codes postaux doivent conserver leurs zéros initiaux. Google donne notamment l’exemple 01234 et recommande un format à cinq caractères dans Google Sheets. Un traitement automatisé doit importer ce champ comme texte et vérifier sa longueur avant la jointure.

Les opérations de ciblage suivent une autre règle. Google exige le GeoTargetConstant exact et n’accepte pas un code ISO ou Nielsen brut à sa place. Le pipeline doit distinguer le libellé d’affichage, le code externe, la clé interne et l’identifiant transmis à Google. Une seule colonne polyvalente crée un risque évitable.

La table finale doit porter un résultat compris par l’entreprise, comme une vente terminée, un revenu brut ou une opportunité acceptée. Ce résultat n’est exploitable dans ce cadre que si le système interne peut le restituer comme total quotidien non négatif pour la géographie du test. Lorsqu’un lead est qualifié après sa création, conservez séparément l’événement initial, le statut de qualification et la date de mise à jour.

• Observation : une date et une unité géographique approuvées par ligne.
• Dépense : coût Google Ads converti, avec cost_micros conservé pour le rapprochement.
• Résultat : total CRM, caisse ou ventes, sans attribution de la plateforme publicitaire.
• Qualification : statut métier défini et contrôlé par les équipes commerciales.
• Fraîcheur : heure d’extraction et dernière journée complète de chaque source.
• Couverture : jours et zones attendus comparés aux éléments réellement présents.
• Exceptions : remboursements, retards, zones manquantes et mappings non résolus.

La documentation de l’API ne fournit ni modèle statistique obligatoire, ni durée minimale, ni budget, ni seuil de lift. Ces paramètres ne doivent pas être inventés à partir de la procédure d’extraction. Ils nécessitent une revue distincte de la conception et de l’historique disponible.

Aucun écart géographique ne devrait être interprété avant la validation de ces contrôles.

• Preuve : requête et réponse brute. Action : reproduire un échantillon. Responsable : ingénierie analytics.
• Preuve : justification de la vue. Action : confirmer géographie utilisateur ou zone ciblée. Responsable : pilote GeoX.
• Preuve : dictionnaire GeoTargetConstant. Action : rejeter toute ressource inconnue. Responsable : data.
• Preuve : définitions CRM. Action : éliminer les filtres d’attribution et confirmer les totaux bruts. Responsable : Revenue Operations.
• Preuve : tests de dates et codes postaux. Action : empêcher tout reformatage automatique. Responsable : qualité des données.
• Preuve : rapprochement par cellule. Action : comparer les totaux sans fusionner les groupes. Responsable : analyste mesure.
• Preuve : journal d’exceptions. Action : expliquer les jours, zones et jointures manquants. Responsable : chef de projet.
• Preuve : validation finale. Action : geler la version ou publier un remplacement versionné. Responsable : relecteur senior.

Il ne faut pas supposer que l’API valide la robustesse statistique du test, que les deux vues sont interchangeables ou qu’un nom de pays lisible est une clé de ciblage. Il ne faut pas non plus confondre conversion attribuée et résultat métier brut. Une jointure réussie prouve la cohérence technique du rapprochement, pas la causalité.

Le point d’entrée prioritaire est un audit Google Ads consacré au contrat GeoX. Le livrable doit couvrir la requête et la vue, la cartographie des champs, le référentiel géographique, le test de conversion monétaire, la définition du résultat CRM, le rapport de qualité des jointures et un registre d’actions priorisées. Il ne doit promettre ni ROAS, ni lift, ni volume de leads.

Lorsque l’audit révèle une question expérimentale mal définie, une unité géographique contestée ou un résultat métier inexploitable, le conseil Google Ads senior constitue l’étape suivante. Pour comparer des prestataires, demandez des exemples de preuves, des responsables nommés, une logique de rapprochement, une gestion des exceptions et une distinction nette entre fonctionnalités Google et méthode de l’agence.

Le parcours Expert Google Ads relie le contrôle des données aux décisions de campagne. Pour poursuivre le diagnostic avec le contexte nécessaire, décrivez à Lia la structure du compte, les zones envisagées, le système métier et les contraintes de données. Une description précise de la situation est plus utile qu’une demande générale de croissance.

Quel service de l’API convient à l’extraction GeoX ?

Google désigne GoogleAdsService et les méthodes Search ou SearchStream. La documentation ne donne pas de règle universelle pour choisir entre les deux ; ce choix doit être justifié dans la conception technique du pipeline.

Faut-il importer les conversions attribuées par Google Ads ?

Pas comme résultats métier dans le workflow décrit. Google demande d’extraire les coûts via l’API et de fournir des conversions ou revenus bruts, non filtrés et non attribués, depuis le CRM, la caisse ou une base de ventes interne.

Quelle vue géographique faut-il choisir ?

geographic_view correspond à la zone où l’utilisateur se trouvait ou pour laquelle il a manifesté un intérêt, et constitue selon Google le cas habituel pour GeoX. location_view porte sur les zones explicitement ciblées par la campagne.

Pourquoi conserver metrics.cost_micros ?

Le coût est renvoyé en micros. Google demande de le diviser par 1 000 000 pour obtenir la valeur monétaire normale. Conserver le champ brut permet de contrôler la transformation et de rapprocher les totaux.

Un code pays ISO suffit-il pour le ciblage ?

Non. Google exige l’identifiant GeoTargetConstant exact lors d’une modification du ciblage. Un code ISO ou Nielsen brut ne peut pas être transmis à sa place.

Quelles propriétés les résultats CRM doivent-ils avoir ?

Ils doivent former une série quotidienne, être reliés aux unités géographiques exactes du test et contenir des totaux absolus non négatifs, comme le revenu brut ou le nombre total de conversions.

Google fixe-t-il la durée ou le seuil de réussite du test ?

Pas dans cette documentation. Elle ne précise ni durée universelle, ni budget, ni taille d’échantillon, ni méthode statistique, ni niveau de lift attendu. Ces paramètres nécessitent une conception distincte.