0
# Campaign Management
1
2
Comprehensive campaign lifecycle management including campaign creation, budget management, campaign settings, and campaign-level targeting and bidding strategies. This covers all aspects of managing Google Ads campaigns from creation to optimization.
3
4
## Capabilities
5
6
### Campaign Service
7
8
Core campaign management operations for creating, updating, and managing Google Ads campaigns.
9
10
```python { .api }
11
class CampaignService:
12
"""Service for managing campaigns."""
13
14
def mutate_campaigns(
15
self,
16
customer_id: str,
17
operations: list,
18
partial_failure: bool = False,
19
validate_only: bool = False,
20
response_content_type: str = None
21
) -> MutateCampaignsResponse:
22
"""
23
Create, update, or delete campaigns.
24
25
Parameters:
26
- customer_id: Customer ID for campaign operations
27
- operations: List of CampaignOperation objects
28
- partial_failure: Continue on individual operation failures
29
- validate_only: Validate operations without executing
30
- response_content_type: Response content type (MUTABLE_RESOURCE, RESOURCE_NAME_ONLY)
31
32
Returns:
33
MutateCampaignsResponse with operation results
34
35
Raises:
36
- GoogleAdsException: If operations fail
37
"""
38
```
39
40
### Campaign Budget Service
41
42
Budget management for campaigns including shared budgets and budget allocation.
43
44
```python { .api }
45
class CampaignBudgetService:
46
"""Service for managing campaign budgets."""
47
48
def mutate_campaign_budgets(
49
self,
50
customer_id: str,
51
operations: list,
52
partial_failure: bool = False,
53
validate_only: bool = False,
54
response_content_type: str = None
55
) -> MutateCampaignBudgetsResponse:
56
"""
57
Create, update, or delete campaign budgets.
58
59
Parameters:
60
- customer_id: Customer ID for budget operations
61
- operations: List of CampaignBudgetOperation objects
62
- partial_failure: Continue on individual operation failures
63
- validate_only: Validate operations without executing
64
- response_content_type: Response content type
65
66
Returns:
67
MutateCampaignBudgetsResponse with operation results
68
69
Raises:
70
- GoogleAdsException: If operations fail
71
"""
72
```
73
74
### Campaign Criterion Service
75
76
Campaign-level targeting criteria including locations, languages, devices, and negative keywords.
77
78
```python { .api }
79
class CampaignCriterionService:
80
"""Service for managing campaign criteria."""
81
82
def mutate_campaign_criteria(
83
self,
84
customer_id: str,
85
operations: list,
86
partial_failure: bool = False,
87
validate_only: bool = False,
88
response_content_type: str = None
89
) -> MutateCampaignCriteriaResponse:
90
"""
91
Create, update, or delete campaign criteria.
92
93
Parameters:
94
- customer_id: Customer ID for criteria operations
95
- operations: List of CampaignCriterionOperation objects
96
- partial_failure: Continue on individual operation failures
97
- validate_only: Validate operations without executing
98
- response_content_type: Response content type
99
100
Returns:
101
MutateCampaignCriteriaResponse with operation results
102
103
Raises:
104
- GoogleAdsException: If operations fail
105
"""
106
```
107
108
### Campaign Asset Service
109
110
Campaign-level asset associations for sitelinks, callouts, structured snippets, and other extensions.
111
112
```python { .api }
113
class CampaignAssetService:
114
"""Service for managing campaign assets."""
115
116
def mutate_campaign_assets(
117
self,
118
customer_id: str,
119
operations: list,
120
partial_failure: bool = False,
121
validate_only: bool = False,
122
response_content_type: str = None
123
) -> MutateCampaignAssetsResponse:
124
"""
125
Create, update, or delete campaign assets.
126
127
Parameters:
128
- customer_id: Customer ID for asset operations
129
- operations: List of CampaignAssetOperation objects
130
- partial_failure: Continue on individual operation failures
131
- validate_only: Validate operations without executing
132
- response_content_type: Response content type
133
134
Returns:
135
MutateCampaignAssetsResponse with operation results
136
137
Raises:
138
- GoogleAdsException: If operations fail
139
"""
140
```
141
142
### Usage Examples
143
144
#### Creating a Search Campaign
145
146
```python
147
from google.ads.googleads.client import GoogleAdsClient
148
from google.ads.googleads.errors import GoogleAdsException
149
150
client = GoogleAdsClient.load_from_storage("google-ads.yaml")
151
campaign_service = client.get_service("CampaignService")
152
campaign_budget_service = client.get_service("CampaignBudgetService")
153
154
# First create a campaign budget
155
budget_operation = client.get_type("CampaignBudgetOperation")
156
budget = budget_operation.create
157
budget.name = "My Campaign Budget"
158
budget.amount_micros = 50000000 # $50 in micros
159
budget.delivery_method = client.enums.BudgetDeliveryMethodEnum.STANDARD
160
budget.explicitly_shared = False
161
162
try:
163
budget_response = campaign_budget_service.mutate_campaign_budgets(
164
customer_id="1234567890",
165
operations=[budget_operation]
166
)
167
168
budget_resource_name = budget_response.results[0].resource_name
169
print(f"Created budget: {budget_resource_name}")
170
171
# Now create the campaign
172
campaign_operation = client.get_type("CampaignOperation")
173
campaign = campaign_operation.create
174
campaign.name = "My Search Campaign"
175
campaign.advertising_channel_type = client.enums.AdvertisingChannelTypeEnum.SEARCH
176
campaign.status = client.enums.CampaignStatusEnum.ENABLED
177
campaign.campaign_budget = budget_resource_name
178
179
# Set bidding strategy
180
campaign.manual_cpc.enhanced_cpc_enabled = True
181
182
# Set campaign settings
183
campaign.start_date = "2024-01-01"
184
campaign.end_date = "2024-12-31"
185
186
# Network settings
187
campaign.network_settings.target_google_search = True
188
campaign.network_settings.target_search_network = True
189
campaign.network_settings.target_content_network = False
190
campaign.network_settings.target_partner_search_network = False
191
192
campaign_response = campaign_service.mutate_campaigns(
193
customer_id="1234567890",
194
operations=[campaign_operation]
195
)
196
197
campaign_resource_name = campaign_response.results[0].resource_name
198
print(f"Created campaign: {campaign_resource_name}")
199
200
except GoogleAdsException as ex:
201
print(f"Campaign creation failed: {ex.error.code().name}")
202
for error in ex.error.details:
203
print(f"Error: {error.message}")
204
```
205
206
#### Setting Up Campaign Targeting
207
208
```python
209
# Add location targeting to campaign
210
campaign_criterion_service = client.get_service("CampaignCriterionService")
211
212
# Target United States
213
location_operation = client.get_type("CampaignCriterionOperation")
214
location_criterion = location_operation.create
215
location_criterion.campaign = campaign_resource_name
216
location_criterion.type_ = client.enums.CriterionTypeEnum.LOCATION
217
location_criterion.location.geo_target_constant = "geoTargetConstants/2840" # USA
218
219
# Add language targeting
220
language_operation = client.get_type("CampaignCriterionOperation")
221
language_criterion = language_operation.create
222
language_criterion.campaign = campaign_resource_name
223
language_criterion.type_ = client.enums.CriterionTypeEnum.LANGUAGE
224
language_criterion.language.language_constant = "languageConstants/1000" # English
225
226
# Add negative keyword
227
negative_keyword_operation = client.get_type("CampaignCriterionOperation")
228
negative_keyword = negative_keyword_operation.create
229
negative_keyword.campaign = campaign_resource_name
230
negative_keyword.negative = True
231
negative_keyword.type_ = client.enums.CriterionTypeEnum.KEYWORD
232
negative_keyword.keyword.text = "free"
233
negative_keyword.keyword.match_type = client.enums.KeywordMatchTypeEnum.BROAD
234
235
try:
236
criterion_response = campaign_criterion_service.mutate_campaign_criteria(
237
customer_id="1234567890",
238
operations=[location_operation, language_operation, negative_keyword_operation]
239
)
240
241
for result in criterion_response.results:
242
print(f"Created criterion: {result.resource_name}")
243
244
except GoogleAdsException as ex:
245
print(f"Targeting setup failed: {ex.error.code().name}")
246
```
247
248
#### Adding Campaign Extensions
249
250
```python
251
# Add sitelink extensions to campaign
252
campaign_asset_service = client.get_service("CampaignAssetService")
253
asset_service = client.get_service("AssetService")
254
255
# First create sitelink assets
256
sitelinks = [
257
{"text": "Contact Us", "url": "https://example.com/contact"},
258
{"text": "About Us", "url": "https://example.com/about"},
259
{"text": "Products", "url": "https://example.com/products"},
260
{"text": "Support", "url": "https://example.com/support"}
261
]
262
263
asset_operations = []
264
for sitelink in sitelinks:
265
asset_operation = client.get_type("AssetOperation")
266
asset = asset_operation.create
267
asset.type_ = client.enums.AssetTypeEnum.SITELINK
268
asset.sitelink_asset.link_text = sitelink["text"]
269
asset.sitelink_asset.final_urls.append(sitelink["url"])
270
asset_operations.append(asset_operation)
271
272
# Create the assets
273
asset_response = asset_service.mutate_assets(
274
customer_id="1234567890",
275
operations=asset_operations
276
)
277
278
# Associate assets with campaign
279
campaign_asset_operations = []
280
for result in asset_response.results:
281
campaign_asset_operation = client.get_type("CampaignAssetOperation")
282
campaign_asset = campaign_asset_operation.create
283
campaign_asset.campaign = campaign_resource_name
284
campaign_asset.asset = result.resource_name
285
campaign_asset.field_type = client.enums.AssetFieldTypeEnum.SITELINK
286
campaign_asset_operations.append(campaign_asset_operation)
287
288
campaign_asset_response = campaign_asset_service.mutate_campaign_assets(
289
customer_id="1234567890",
290
operations=campaign_asset_operations
291
)
292
293
print(f"Added {len(campaign_asset_response.results)} sitelinks to campaign")
294
```
295
296
#### Campaign Performance Optimization
297
298
```python
299
# Update campaign bidding strategy and settings
300
update_operation = client.get_type("CampaignOperation")
301
update_campaign = update_operation.update
302
update_campaign.resource_name = campaign_resource_name
303
304
# Switch to Target CPA bidding
305
update_campaign.target_cpa.target_cpa_micros = 5000000 # $5.00 target CPA
306
307
# Update ad schedule (Monday-Friday, 9 AM - 6 PM)
308
ad_schedule = client.get_type("CampaignCriterionOperation")
309
schedule_criterion = ad_schedule.create
310
schedule_criterion.campaign = campaign_resource_name
311
schedule_criterion.type_ = client.enums.CriterionTypeEnum.AD_SCHEDULE
312
schedule_criterion.ad_schedule.minute_of_hour = client.enums.MinuteOfHourEnum.ZERO
313
schedule_criterion.ad_schedule.start_hour = 9
314
schedule_criterion.ad_schedule.end_hour = 18
315
schedule_criterion.ad_schedule.day_of_week = client.enums.DayOfWeekEnum.MONDAY
316
317
# Set update mask to specify which fields to update
318
field_mask = client.get_type("FieldMask")
319
field_mask.paths.extend(["target_cpa.target_cpa_micros"])
320
update_operation.update_mask = field_mask
321
322
try:
323
# Update campaign
324
update_response = campaign_service.mutate_campaigns(
325
customer_id="1234567890",
326
operations=[update_operation]
327
)
328
329
# Add ad schedule
330
schedule_response = campaign_criterion_service.mutate_campaign_criteria(
331
customer_id="1234567890",
332
operations=[ad_schedule]
333
)
334
335
print("Campaign optimization completed")
336
337
except GoogleAdsException as ex:
338
print(f"Campaign update failed: {ex.error.code().name}")
339
```
340
341
#### Campaign Reporting
342
343
```python
344
# Get campaign performance data
345
googleads_service = client.get_service("GoogleAdsService")
346
347
campaign_query = """
348
SELECT
349
campaign.id,
350
campaign.name,
351
campaign.status,
352
campaign.advertising_channel_type,
353
campaign.bidding_strategy_type,
354
campaign_budget.amount_micros,
355
metrics.impressions,
356
metrics.clicks,
357
metrics.cost_micros,
358
metrics.ctr,
359
metrics.average_cpc,
360
metrics.conversions,
361
metrics.conversions_value,
362
metrics.cost_per_conversion
363
FROM campaign
364
WHERE campaign.status IN ('ENABLED', 'PAUSED')
365
AND segments.date DURING LAST_30_DAYS
366
ORDER BY metrics.cost_micros DESC
367
"""
368
369
try:
370
response = googleads_service.search(
371
customer_id="1234567890",
372
query=campaign_query
373
)
374
375
print("Campaign Performance Report")
376
print("=" * 50)
377
378
for row in response:
379
c = row.campaign
380
m = row.metrics
381
b = row.campaign_budget
382
383
print(f"Campaign: {c.name} (ID: {c.id})")
384
print(f"Status: {c.status.name}")
385
print(f"Type: {c.advertising_channel_type.name}")
386
print(f"Bidding: {c.bidding_strategy_type.name}")
387
print(f"Budget: ${b.amount_micros / 1_000_000:.2f}")
388
print(f"Impressions: {m.impressions:,}")
389
print(f"Clicks: {m.clicks:,}")
390
print(f"Cost: ${m.cost_micros / 1_000_000:.2f}")
391
print(f"CTR: {m.ctr:.2%}")
392
print(f"Avg CPC: ${m.average_cpc / 1_000_000:.2f}")
393
print(f"Conversions: {m.conversions}")
394
print(f"Conv. Value: ${m.conversions_value:.2f}")
395
if m.conversions > 0:
396
print(f"Cost/Conv: ${m.cost_per_conversion / 1_000_000:.2f}")
397
print("-" * 30)
398
399
except GoogleAdsException as ex:
400
print(f"Report generation failed: {ex.error.code().name}")
401
```
402
403
## Operation Types
404
405
```python { .api }
406
class CampaignOperation:
407
"""Operation for campaign mutations."""
408
create: Campaign # Create new campaign
409
update: Campaign # Update existing campaign
410
remove: str # Remove campaign by resource name
411
update_mask: FieldMask # Fields to update
412
413
class CampaignBudgetOperation:
414
"""Operation for campaign budget mutations."""
415
create: CampaignBudget # Create new budget
416
update: CampaignBudget # Update existing budget
417
remove: str # Remove budget by resource name
418
update_mask: FieldMask # Fields to update
419
420
class CampaignCriterionOperation:
421
"""Operation for campaign criterion mutations."""
422
create: CampaignCriterion # Create new criterion
423
update: CampaignCriterion # Update existing criterion
424
remove: str # Remove criterion by resource name
425
update_mask: FieldMask # Fields to update
426
```
427
428
## Resource Types
429
430
```python { .api }
431
class Campaign:
432
"""Campaign resource."""
433
resource_name: str # Campaign resource name
434
name: str # Campaign name
435
status: CampaignStatusEnum # Campaign status
436
advertising_channel_type: AdvertisingChannelTypeEnum # Channel type
437
advertising_channel_sub_type: AdvertisingChannelSubTypeEnum # Sub type
438
campaign_budget: str # Budget resource name
439
bidding_strategy_type: BiddingStrategyTypeEnum # Bidding strategy
440
start_date: str # Start date (YYYY-MM-DD)
441
end_date: str # End date (YYYY-MM-DD)
442
network_settings: NetworkSettings # Network targeting
443
manual_cpc: ManualCpc # Manual CPC settings
444
target_cpa: TargetCpa # Target CPA settings
445
target_roas: TargetRoas # Target ROAS settings
446
maximize_clicks: MaximizeClicks # Maximize clicks settings
447
maximize_conversions: MaximizeConversions # Maximize conversions settings
448
449
class CampaignBudget:
450
"""Campaign budget resource."""
451
resource_name: str # Budget resource name
452
name: str # Budget name
453
amount_micros: int # Budget amount in micros
454
delivery_method: BudgetDeliveryMethodEnum # Delivery method
455
explicitly_shared: bool # Whether budget is shared
456
status: BudgetStatusEnum # Budget status
457
type_: BudgetTypeEnum # Budget type
458
459
class CampaignCriterion:
460
"""Campaign criterion resource."""
461
resource_name: str # Criterion resource name
462
campaign: str # Campaign resource name
463
type_: CriterionTypeEnum # Criterion type
464
negative: bool # Whether criterion is negative
465
location: LocationInfo # Location targeting
466
language: LanguageInfo # Language targeting
467
keyword: KeywordInfo # Keyword targeting
468
ad_schedule: AdScheduleInfo # Ad schedule
469
device: DeviceInfo # Device targeting
470
```
471
472
## Enums
473
474
```python { .api }
475
# Campaign status values
476
class CampaignStatusEnum:
477
UNKNOWN = 0
478
ENABLED = 2
479
PAUSED = 3
480
REMOVED = 4
481
482
# Advertising channel types
483
class AdvertisingChannelTypeEnum:
484
UNKNOWN = 0
485
SEARCH = 2
486
DISPLAY = 3
487
SHOPPING = 4
488
VIDEO = 6
489
MULTI_CHANNEL = 7
490
LOCAL = 8
491
SMART = 9
492
PERFORMANCE_MAX = 13
493
494
# Bidding strategy types
495
class BiddingStrategyTypeEnum:
496
UNKNOWN = 0
497
MANUAL_CPC = 2
498
MANUAL_CPM = 3
499
MANUAL_CPV = 5
500
MAXIMIZE_CLICKS = 10
501
MAXIMIZE_CONVERSIONS = 11
502
MAXIMIZE_CONVERSION_VALUE = 12
503
TARGET_CPA = 13
504
TARGET_IMPRESSION_SHARE = 15
505
TARGET_ROAS = 16
506
TARGET_CPM = 17
507
508
# Budget delivery methods
509
class BudgetDeliveryMethodEnum:
510
UNKNOWN = 0
511
STANDARD = 2
512
ACCELERATED = 3
513
```
514
515
## Constants
516
517
```python { .api }
518
# Micro unit conversions
519
MICROS_PER_UNIT = 1_000_000
520
521
# Campaign limits
522
MAX_CAMPAIGN_NAME_LENGTH = 255
523
MAX_CAMPAIGNS_PER_CUSTOMER = 10000
524
525
# Budget limits
526
MIN_BUDGET_AMOUNT_MICROS = 100_000 # $0.10
527
MAX_BUDGET_AMOUNT_MICROS = 100_000_000_000 # $100,000
528
529
# Date format
530
DATE_FORMAT = "YYYY-MM-DD"
531
```