Google Ads API avec Python : tutoriel complet pour débutants

Python est le langage de référence pour interagir avec Google Ads API. Sa bibliothèque officielle google-ads simplifie l’authentification, la gestion des erreurs et l’exécution des requêtes. Ce tutoriel vous guide pas à pas de l’installation jusqu’à vos premiers appels en production.

Prérequis avant de commencer

• ✅ Un developer token Google Ads API approuvé
• ✅ Un projet Google Cloud avec l’API Google Ads activée
• ✅ Des credentials OAuth2 (client_id, client_secret, refresh_token)
• ✅ Python 3.8 ou supérieur installé

Si vous n’avez pas encore votre developer token, consultez notre guide sur comment obtenir l’accès à la Google Ads API (developer token et OAuth2).

Installation de la bibliothèque Python Google Ads

python -m venv venv
source venv/bin/activate
pip install google-ads pandas google-cloud-bigquery python-dotenv

Configuration du fichier google-ads.yaml

# google-ads.yaml
developer_token: "VOTRE_DEVELOPER_TOKEN"
client_id: "VOTRE_CLIENT_ID.apps.googleusercontent.com"
client_secret: "VOTRE_CLIENT_SECRET"
refresh_token: "VOTRE_REFRESH_TOKEN"
login_customer_id: "VOTRE_MCC_ID"
use_proto_plus: true

⚠️ N’engagez jamais ce fichier dans Git. Ajoutez-le immédiatement à votre .gitignore.

Premier appel API : lister vos campagnes

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage("google-ads.yaml")
ga_service = client.get_service("GoogleAdsService")

query = """
    SELECT campaign.id, campaign.name, campaign.status
    FROM campaign
    WHERE campaign.status = 'ENABLED'
    ORDER BY campaign.name
"""

customer_id = "VOTRE_CUSTOMER_ID"
response = ga_service.search(customer_id=customer_id, query=query)

for row in response:
    print(f"ID: {row.campaign.id} | Nom: {row.campaign.name}")

Créer une campagne via Python

from google.ads.googleads.client import GoogleAdsClient

def create_campaign(client, customer_id, campaign_name, budget_id):
    campaign_service = client.get_service("CampaignService")
    campaign_operation = client.get_type("CampaignOperation")
    campaign = campaign_operation.create
    
    campaign.name = campaign_name
    campaign.advertising_channel_type = (
        client.enums.AdvertisingChannelTypeEnum.SEARCH
    )
    campaign.status = client.enums.CampaignStatusEnum.PAUSED
    campaign.campaign_budget = f"customers/{customer_id}/campaignBudgets/{budget_id}"
    campaign.manual_cpc.enhanced_cpc_enabled = True
    
    response = campaign_service.mutate_campaigns(
        customer_id=customer_id,
        operations=[campaign_operation]
    )
    print(f"Campagne créée: {response.results[0].resource_name}")
    return response

Gestion des erreurs Google Ads API

from google.ads.googleads.errors import GoogleAdsException

try:
    response = ga_service.search(customer_id=customer_id, query=query)
except GoogleAdsException as ex:
    print(f"Requête échouée avec statut: {ex.error.code().name}")
    for error in ex.failure.errors:
        print(f"Erreur: {error.message}")
        if error.location:
            for field_path in error.location.field_path_elements:
                print(f"Champ: {field_path.field_name}")

Requêtes GAQL avancées : métriques et segments

# Rapport de performance avec segments par device
query = """
    SELECT
        campaign.name,
        segments.device,
        segments.date,
        metrics.clicks,
        metrics.impressions,
        metrics.cost_micros,
        metrics.conversions,
        metrics.all_conversions_value
    FROM campaign
    WHERE segments.date DURING LAST_7_DAYS
        AND campaign.status IN ('ENABLED', 'PAUSED')
    ORDER BY metrics.cost_micros DESC
    LIMIT 100
"""

FAQ — Google Ads API Python

Quelle version de la bibliothèque Python utiliser ?

Utilisez toujours la dernière version stable via pip install --upgrade google-ads. La v24 de l’API correspond à la bibliothèque Python 24.x.x.

search() vs search_stream() : quelle différence ?

search() est adapté aux petits volumes (moins de 10 000 lignes). search_stream() est obligatoire pour les grands volumes car il évite les timeouts et les limitations de pagination.

Comment déboguer une erreur INVALID_ARGUMENT ?

Activez le logging détaillé avec logging.basicConfig(level=logging.DEBUG) avant votre appel API. Google retourne des messages d’erreur précis avec le champ problématique et la valeur invalide.

Pour aller plus loin, consultez notre guide complet Google Ads API v24 avec tous les nouveaux champs disponibles. Maîtrisez les quotas et limites avant de passer en production. Pour construire un pipeline de reporting complet, lisez notre guide sur l’automatisation des rapports Google Ads avec l’API. Et si vous venez des Scripts, comparez les deux approches dans notre article Google Ads Scripts vs API.