0
# Google Ads Python Client Library
1
2
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.
3
4
## Package Information
5
6
- **Package Name**: google-ads
7
- **Language**: Python
8
- **Installation**: `pip install google-ads`
9
- **API Versions**: v19, v20, v21 (latest)
10
- **Python Compatibility**: 3.9+
11
12
## Core Imports
13
14
```python
15
from google.ads.googleads.client import GoogleAdsClient
16
from google.ads.googleads.errors import GoogleAdsException
17
```
18
19
Common imports for specific functionality:
20
21
```python
22
# Configuration and authentication
23
from google.ads.googleads import config, oauth2
24
25
# Utilities
26
from google.ads.googleads import util
27
```
28
29
## Basic Usage
30
31
```python
32
from google.ads.googleads.client import GoogleAdsClient
33
from google.ads.googleads.errors import GoogleAdsException
34
35
# Initialize client from YAML file
36
client = GoogleAdsClient.load_from_storage("google-ads.yaml")
37
38
# Or from environment variables
39
client = GoogleAdsClient.load_from_env()
40
41
# Get a service client
42
googleads_service = client.get_service("GoogleAdsService")
43
campaign_service = client.get_service("CampaignService")
44
45
# Perform a search query
46
query = """
47
SELECT
48
campaign.id,
49
campaign.name,
50
campaign.status,
51
metrics.impressions,
52
metrics.clicks
53
FROM campaign
54
WHERE campaign.status = 'ENABLED'
55
"""
56
57
try:
58
response = googleads_service.search(
59
customer_id="1234567890",
60
query=query
61
)
62
63
for row in response:
64
campaign = row.campaign
65
metrics = row.metrics
66
print(f"Campaign: {campaign.name} (ID: {campaign.id})")
67
print(f"Status: {campaign.status}")
68
print(f"Impressions: {metrics.impressions}, Clicks: {metrics.clicks}")
69
70
except GoogleAdsException as ex:
71
print(f"Request failed with status {ex.error.code().name}")
72
print(f"Request ID: {ex.request_id}")
73
```
74
75
## Architecture
76
77
The Google Ads Python client library follows a service-oriented architecture:
78
79
- **GoogleAdsClient**: Central client for authentication, service access, and configuration management
80
- **Service Clients**: Specialized clients for different API areas (campaigns, ads, keywords, etc.)
81
- **API Versions**: Multiple supported API versions (v19, v20, v21) with identical interfaces
82
- **Message Types**: Structured data classes for requests, responses, and resources
83
- **Enums**: Strongly-typed enumeration values accessible via client.enums
84
- **Interceptors**: Automatic handling of authentication, logging, and error processing
85
86
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.
87
88
## Capabilities
89
90
### Client Setup and Authentication
91
92
Core client initialization, configuration management, and authentication flows including OAuth2 and service account authentication.
93
94
```python { .api }
95
class GoogleAdsClient:
96
def __init__(
97
self,
98
credentials,
99
developer_token: str,
100
endpoint: str = None,
101
login_customer_id: str = None,
102
logging_config: dict = None,
103
linked_customer_id: str = None,
104
version: str = None,
105
http_proxy: str = None,
106
use_proto_plus: bool = False,
107
use_cloud_org_for_api_access: str = None
108
): ...
109
110
@classmethod
111
def load_from_storage(cls, path: str = None, version: str = None) -> 'GoogleAdsClient': ...
112
113
@classmethod
114
def load_from_env(cls, version: str = None) -> 'GoogleAdsClient': ...
115
116
@classmethod
117
def load_from_string(cls, yaml_str: str, version: str = None) -> 'GoogleAdsClient': ...
118
119
@classmethod
120
def load_from_dict(cls, config_dict: dict, version: str = None) -> 'GoogleAdsClient': ...
121
122
@classmethod
123
def copy_from(cls, destination, origin): ...
124
125
def get_service(self, name: str, version: str = None, interceptors: list = None) -> object: ...
126
127
def get_type(self, name: str, version: str = None) -> object: ...
128
```
129
130
[Client Setup and Authentication](./client-setup.md)
131
132
### Campaign Management
133
134
Comprehensive campaign lifecycle management including campaign creation, budget management, campaign settings, and campaign-level targeting and bidding strategies.
135
136
```python { .api }
137
# Campaign Service
138
def mutate_campaigns(
139
self,
140
customer_id: str,
141
operations: list,
142
partial_failure: bool = False,
143
validate_only: bool = False
144
) -> object: ...
145
146
# Campaign Budget Service
147
def mutate_campaign_budgets(
148
self,
149
customer_id: str,
150
operations: list,
151
partial_failure: bool = False,
152
validate_only: bool = False
153
) -> object: ...
154
```
155
156
[Campaign Management](./campaign-management.md)
157
158
### Ad Management
159
160
Ad group and ad creation, management, and optimization including ad group settings, ad creation, ad extensions, and ad-level targeting and bidding.
161
162
```python { .api }
163
# Ad Group Service
164
def mutate_ad_groups(
165
self,
166
customer_id: str,
167
operations: list,
168
partial_failure: bool = False,
169
validate_only: bool = False
170
) -> object: ...
171
172
# Ad Group Ad Service
173
def mutate_ad_group_ads(
174
self,
175
customer_id: str,
176
operations: list,
177
partial_failure: bool = False,
178
validate_only: bool = False
179
) -> object: ...
180
```
181
182
[Ad Management](./ad-management.md)
183
184
### Targeting and Keywords
185
186
Keyword research, planning, and targeting including keyword plan creation, keyword ideas generation, geographic targeting, and audience targeting.
187
188
```python { .api }
189
# Keyword Plan Idea Service
190
def generate_keyword_ideas(
191
self,
192
customer_id: str,
193
request: object
194
) -> object: ...
195
196
# Geo Target Constant Service
197
def suggest_geo_target_constants(
198
self,
199
request: object
200
) -> object: ...
201
```
202
203
[Targeting and Keywords](./targeting-keywords.md)
204
205
### Reporting and Search
206
207
Comprehensive reporting capabilities using the Google Ads Query Language (GAQL) for data retrieval, performance analysis, and custom reporting.
208
209
```python { .api }
210
# Google Ads Service
211
def search(
212
self,
213
customer_id: str,
214
query: str,
215
page_size: int = None,
216
return_total_results_count: bool = False
217
) -> object: ...
218
219
def search_stream(
220
self,
221
customer_id: str,
222
query: str
223
) -> object: ...
224
```
225
226
[Reporting and Search](./reporting-search.md)
227
228
### Audience Management
229
230
User list creation and management, custom audience definition, audience insights, and audience-based targeting strategies.
231
232
```python { .api }
233
# User List Service
234
def mutate_user_lists(
235
self,
236
customer_id: str,
237
operations: list,
238
partial_failure: bool = False,
239
validate_only: bool = False
240
) -> object: ...
241
242
# Audience Insights Service
243
def generate_audience_composition_insights(
244
self,
245
customer_id: str,
246
request: object
247
) -> object: ...
248
```
249
250
[Audience Management](./audience-management.md)
251
252
### Asset Management
253
254
Asset creation, management, and association including images, videos, text assets, asset groups, and asset-based campaign types.
255
256
```python { .api }
257
# Asset Service
258
def mutate_assets(
259
self,
260
customer_id: str,
261
operations: list,
262
partial_failure: bool = False,
263
validate_only: bool = False
264
) -> object: ...
265
266
# Asset Group Service
267
def mutate_asset_groups(
268
self,
269
customer_id: str,
270
operations: list,
271
partial_failure: bool = False,
272
validate_only: bool = False
273
) -> object: ...
274
```
275
276
[Asset Management](./asset-management.md)
277
278
### Conversion Tracking
279
280
Conversion action setup, conversion data upload, conversion value optimization, and attribution model configuration.
281
282
```python { .api }
283
# Conversion Action Service
284
def mutate_conversion_actions(
285
self,
286
customer_id: str,
287
operations: list,
288
partial_failure: bool = False,
289
validate_only: bool = False
290
) -> object: ...
291
292
# Conversion Upload Service
293
def upload_click_conversions(
294
self,
295
customer_id: str,
296
conversions: list,
297
partial_failure: bool = False,
298
validate_only: bool = False
299
) -> object: ...
300
```
301
302
[Conversion Tracking](./conversion-tracking.md)
303
304
### Batch Operations
305
306
Efficient bulk operations using batch jobs and offline data processing for large-scale account management and data synchronization.
307
308
```python { .api }
309
# Batch Job Service
310
def add_batch_job_operations(
311
self,
312
resource_name: str,
313
mutate_operations: list
314
) -> object: ...
315
316
def run_batch_job(
317
self,
318
resource_name: str
319
) -> object: ...
320
```
321
322
[Batch Operations](./batch-operations.md)
323
324
### Specialized Services
325
326
Advanced features including experiments, reach planning, smart campaigns, brand suggestions, and other specialized Google Ads functionality.
327
328
```python { .api }
329
# Reach Plan Service
330
def generate_reach_forecast(
331
self,
332
customer_id: str,
333
request: object
334
) -> object: ...
335
336
# Experiment Service
337
def mutate_experiments(
338
self,
339
customer_id: str,
340
operations: list,
341
validate_only: bool = False
342
) -> object: ...
343
```
344
345
346
## Error Handling
347
348
```python { .api }
349
class GoogleAdsException(Exception):
350
"""Main exception class for Google Ads API errors."""
351
352
def __init__(self, error, call, request_id: str = None): ...
353
354
@property
355
def error(self): ...
356
357
@property
358
def call(self): ...
359
360
@property
361
def request_id(self) -> str: ...
362
```
363
364
## Common Types
365
366
```python { .api }
367
# Core client class
368
class GoogleAdsClient:
369
credentials: object
370
developer_token: str
371
endpoint: str
372
login_customer_id: str
373
linked_customer_id: str
374
version: str
375
http_proxy: str
376
use_proto_plus: bool
377
use_cloud_org_for_api_access: str
378
enums: object
379
380
# Configuration data structure
381
ConfigData = dict[str, str]
382
383
# Operation response structure
384
MutateOperationResponse = object
385
386
# Search response structure
387
SearchGoogleAdsResponse = object