or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

ad-management.mdasset-management.mdaudience-management.mdbatch-operations.mdcampaign-management.mdclient-setup.mdconversion-tracking.mdindex.mdreporting-search.mdtargeting-keywords.md
tile.json

tessl/pypi-google-ads

Client library for the Google Ads API providing comprehensive access to advertising management, reporting, and analytics capabilities.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/google-ads@28.0.x

To install, run

npx @tessl/cli install tessl/pypi-google-ads@28.0.0

index.mddocs/

Google Ads Python Client Library

A comprehensive Python client library for the Google Ads API, enabling developers to programmatically manage and interact with Google Ads campaigns, keywords, ads, and reporting data. The library offers easy credential management, streamlined service client creation, and full access to the Google Ads API functionality through Python objects and methods.

Package Information

  • Package Name: google-ads
  • Language: Python
  • Installation: pip install google-ads
  • API Versions: v19, v20, v21 (latest)
  • Python Compatibility: 3.9+

Core Imports

from google.ads.googleads.client import GoogleAdsClient
from google.ads.googleads.errors import GoogleAdsException

Common imports for specific functionality:

# Configuration and authentication
from google.ads.googleads import config, oauth2

# Utilities
from google.ads.googleads import util

Basic Usage

from google.ads.googleads.client import GoogleAdsClient
from google.ads.googleads.errors import GoogleAdsException

# Initialize client from YAML file
client = GoogleAdsClient.load_from_storage("google-ads.yaml")

# Or from environment variables
client = GoogleAdsClient.load_from_env()

# Get a service client
googleads_service = client.get_service("GoogleAdsService")
campaign_service = client.get_service("CampaignService")

# Perform a search query
query = """
    SELECT 
        campaign.id, 
        campaign.name, 
        campaign.status,
        metrics.impressions,
        metrics.clicks
    FROM campaign 
    WHERE campaign.status = 'ENABLED'
"""

try:
    response = googleads_service.search(
        customer_id="1234567890", 
        query=query
    )
    
    for row in response:
        campaign = row.campaign
        metrics = row.metrics
        print(f"Campaign: {campaign.name} (ID: {campaign.id})")
        print(f"Status: {campaign.status}")
        print(f"Impressions: {metrics.impressions}, Clicks: {metrics.clicks}")
        
except GoogleAdsException as ex:
    print(f"Request failed with status {ex.error.code().name}")
    print(f"Request ID: {ex.request_id}")

Architecture

The Google Ads Python client library follows a service-oriented architecture:

  • GoogleAdsClient: Central client for authentication, service access, and configuration management
  • Service Clients: Specialized clients for different API areas (campaigns, ads, keywords, etc.)
  • API Versions: Multiple supported API versions (v19, v20, v21) with identical interfaces
  • Message Types: Structured data classes for requests, responses, and resources
  • Enums: Strongly-typed enumeration values accessible via client.enums
  • Interceptors: Automatic handling of authentication, logging, and error processing

The client uses gRPC for high-performance communication with the Google Ads API, supporting both unary (request-response) and streaming operations for large data sets.

Capabilities

Client Setup and Authentication

Core client initialization, configuration management, and authentication flows including OAuth2 and service account authentication.

class GoogleAdsClient:
    def __init__(
        self,
        credentials,
        developer_token: str,
        endpoint: str = None,
        login_customer_id: str = None,
        logging_config: dict = None,
        linked_customer_id: str = None,
        version: str = None,
        http_proxy: str = None,
        use_proto_plus: bool = False,
        use_cloud_org_for_api_access: str = None
    ): ...
    
    @classmethod
    def load_from_storage(cls, path: str = None, version: str = None) -> 'GoogleAdsClient': ...
    
    @classmethod 
    def load_from_env(cls, version: str = None) -> 'GoogleAdsClient': ...
    
    @classmethod
    def load_from_string(cls, yaml_str: str, version: str = None) -> 'GoogleAdsClient': ...
    
    @classmethod
    def load_from_dict(cls, config_dict: dict, version: str = None) -> 'GoogleAdsClient': ...
    
    @classmethod
    def copy_from(cls, destination, origin): ...
    
    def get_service(self, name: str, version: str = None, interceptors: list = None) -> object: ...
    
    def get_type(self, name: str, version: str = None) -> object: ...

Client Setup and Authentication

Campaign Management

Comprehensive campaign lifecycle management including campaign creation, budget management, campaign settings, and campaign-level targeting and bidding strategies.

# Campaign Service
def mutate_campaigns(
    self,
    customer_id: str,
    operations: list,
    partial_failure: bool = False,
    validate_only: bool = False
) -> object: ...

# Campaign Budget Service  
def mutate_campaign_budgets(
    self,
    customer_id: str,
    operations: list,
    partial_failure: bool = False,
    validate_only: bool = False
) -> object: ...

Campaign Management

Ad Management

Ad group and ad creation, management, and optimization including ad group settings, ad creation, ad extensions, and ad-level targeting and bidding.

# Ad Group Service
def mutate_ad_groups(
    self,
    customer_id: str,
    operations: list,
    partial_failure: bool = False,
    validate_only: bool = False
) -> object: ...

# Ad Group Ad Service
def mutate_ad_group_ads(
    self,
    customer_id: str,
    operations: list,
    partial_failure: bool = False,
    validate_only: bool = False
) -> object: ...

Ad Management

Targeting and Keywords

Keyword research, planning, and targeting including keyword plan creation, keyword ideas generation, geographic targeting, and audience targeting.

# Keyword Plan Idea Service
def generate_keyword_ideas(
    self,
    customer_id: str,
    request: object
) -> object: ...

# Geo Target Constant Service
def suggest_geo_target_constants(
    self,
    request: object
) -> object: ...

Targeting and Keywords

Reporting and Search

Comprehensive reporting capabilities using the Google Ads Query Language (GAQL) for data retrieval, performance analysis, and custom reporting.

# Google Ads Service
def search(
    self,
    customer_id: str,
    query: str,
    page_size: int = None,
    return_total_results_count: bool = False
) -> object: ...

def search_stream(
    self,
    customer_id: str,
    query: str
) -> object: ...

Reporting and Search

Audience Management

User list creation and management, custom audience definition, audience insights, and audience-based targeting strategies.

# User List Service
def mutate_user_lists(
    self,
    customer_id: str,
    operations: list,
    partial_failure: bool = False,
    validate_only: bool = False
) -> object: ...

# Audience Insights Service
def generate_audience_composition_insights(
    self,
    customer_id: str,
    request: object
) -> object: ...

Audience Management

Asset Management

Asset creation, management, and association including images, videos, text assets, asset groups, and asset-based campaign types.

# Asset Service
def mutate_assets(
    self,
    customer_id: str,
    operations: list,
    partial_failure: bool = False,
    validate_only: bool = False
) -> object: ...

# Asset Group Service
def mutate_asset_groups(
    self,
    customer_id: str,
    operations: list,
    partial_failure: bool = False,
    validate_only: bool = False
) -> object: ...

Asset Management

Conversion Tracking

Conversion action setup, conversion data upload, conversion value optimization, and attribution model configuration.

# Conversion Action Service
def mutate_conversion_actions(
    self,
    customer_id: str,
    operations: list,
    partial_failure: bool = False,
    validate_only: bool = False
) -> object: ...

# Conversion Upload Service
def upload_click_conversions(
    self,
    customer_id: str,
    conversions: list,
    partial_failure: bool = False,
    validate_only: bool = False
) -> object: ...

Conversion Tracking

Batch Operations

Efficient bulk operations using batch jobs and offline data processing for large-scale account management and data synchronization.

# Batch Job Service
def add_batch_job_operations(
    self,
    resource_name: str,
    mutate_operations: list
) -> object: ...

def run_batch_job(
    self,
    resource_name: str
) -> object: ...

Batch Operations

Specialized Services

Advanced features including experiments, reach planning, smart campaigns, brand suggestions, and other specialized Google Ads functionality.

# Reach Plan Service
def generate_reach_forecast(
    self,
    customer_id: str,
    request: object
) -> object: ...

# Experiment Service
def mutate_experiments(
    self,
    customer_id: str,
    operations: list,
    validate_only: bool = False
) -> object: ...

Error Handling

class GoogleAdsException(Exception):
    """Main exception class for Google Ads API errors."""
    
    def __init__(self, error, call, request_id: str = None): ...
    
    @property
    def error(self): ...
    
    @property 
    def call(self): ...
    
    @property
    def request_id(self) -> str: ...

Common Types

# Core client class
class GoogleAdsClient:
    credentials: object
    developer_token: str
    endpoint: str
    login_customer_id: str
    linked_customer_id: str
    version: str
    http_proxy: str
    use_proto_plus: bool
    use_cloud_org_for_api_access: str
    enums: object

# Configuration data structure
ConfigData = dict[str, str]

# Operation response structure  
MutateOperationResponse = object

# Search response structure
SearchGoogleAdsResponse = object