Skip to content

Commit 568b111

Browse files
BenRKarlBenRKarl
authored
Add New Planning Examples (#71)
1 parent 6a2f334 commit 568b111

File tree

2 files changed

+368
-0
lines changed

2 files changed

+368
-0
lines changed

‎examples/planning/add_keyword_plan.py‎

Lines changed: 289 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,289 @@
1+
# Copyright 2019 Google LLC
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# https://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
"""This example creates a keyword plan.
15+
16+
Keyword plans can be reused for retrieving forecast metrics and historic
17+
metrics.
18+
"""
19+
20+
from __future__ import absolute_import
21+
22+
import argparse
23+
import six
24+
import sys
25+
import uuid
26+
27+
from google.ads.google_ads.client import GoogleAdsClient
28+
from google.ads.google_ads.errors import GoogleAdsException
29+
30+
31+
def main(client, customer_id):
32+
"""Adds a keyword plan, campaign, ad group, etc. to the customer account
33+
34+
Also handles errors from the API and prints them.
35+
36+
Args:
37+
client: An initialized instance of GoogleAdsClient
38+
customer_id: A str of the customer_id to use in requests.
39+
"""
40+
try:
41+
add_keyword_plan(client, customer_id)
42+
except GoogleAdsException as ex:
43+
print('Request with ID "{}" failed with status "{}" and includes the '
44+
'following errors:'.format(ex.request_id, ex.error.code().name))
45+
for error in ex.failure.errors:
46+
print('\tError with message "{}".'.format(error.message))
47+
if error.location:
48+
for field_path_element in error.location.field_path_elements:
49+
print('\t\tOn field: {}'.format(
50+
field_path_element.field_name))
51+
sys.exit(1)
52+
53+
54+
def add_keyword_plan(client, customer_id):
55+
"""Adds a keyword plan, campaign, ad group, etc. to the customer account.
56+
57+
Args:
58+
client: An initialized instance of GoogleAdsClient
59+
customer_id: A str of the customer_id to use in requests.
60+
61+
Raises:
62+
GoogleAdsException: If an error is returned from the API.
63+
"""
64+
keyword_plan = create_keyword_plan(client, customer_id)
65+
keyword_plan_campaign = create_keyword_plan_campaign(client, customer_id,
66+
keyword_plan)
67+
keyword_plan_ad_group = create_keyword_plan_ad_group(client, customer_id,
68+
keyword_plan_campaign)
69+
create_keyword_plan_keywords(client, customer_id, keyword_plan_ad_group)
70+
create_keyword_plan_negative_keywords(client, customer_id,
71+
keyword_plan_campaign)
72+
73+
74+
def create_keyword_plan(client, customer_id):
75+
"""Adds a keyword plan to the given customer account.
76+
77+
Args:
78+
client: An initialized instance of GoogleAdsClient
79+
customer_id: A str of the customer_id to use in requests.
80+
81+
Returns:
82+
A str of the resource_name for the newly created keyword plan.
83+
84+
Raises:
85+
GoogleAdsException: If an error is returned from the API.
86+
"""
87+
operation = client.get_type('KeywordPlanOperation', version='v1')
88+
keyword_plan = operation.create
89+
90+
keyword_plan.name.value = ('Keyword plan for traffic estimate {}'.format(
91+
uuid.uuid4()))
92+
93+
forecast_interval = client.get_type('KeywordPlanForecastIntervalEnum',
94+
version='v1').NEXT_QUARTER
95+
keyword_plan.forecast_period.date_interval = forecast_interval
96+
97+
keyword_plan_service = client.get_service('KeywordPlanService',
98+
version='v1')
99+
response = keyword_plan_service.mutate_keyword_plans(customer_id,
100+
[operation])
101+
resource_name = response.results[0].resource_name
102+
103+
print('Created keyword plan with resource name: {}'.format(resource_name))
104+
105+
return resource_name
106+
107+
108+
def create_keyword_plan_campaign(client, customer_id, keyword_plan):
109+
"""Adds a keyword plan campaign to the given keyword plan.
110+
111+
Args:
112+
client: An initialized instance of GoogleAdsClient
113+
customer_id: A str of the customer_id to use in requests.
114+
keyword_plan: A str of the keyword plan resource_name this keyword plan
115+
campaign should be attributed to.create_keyword_plan.
116+
117+
Returns:
118+
A str of the resource_name for the newly created keyword plan campaign.
119+
120+
Raises:
121+
GoogleAdsException: If an error is returned from the API.
122+
"""
123+
operation = client.get_type('KeywordPlanCampaignOperation', version='v1')
124+
keyword_plan_campaign = operation.create
125+
126+
keyword_plan_campaign.name.value = 'Keyword plan campaign {}'.format(
127+
uuid.uuid4())
128+
keyword_plan_campaign.cpc_bid_micros.value = 1000000
129+
keyword_plan_campaign.keyword_plan.value = keyword_plan
130+
131+
keyword_plan_network = client.get_type('KeywordPlanNetworkEnum',
132+
version='v1')
133+
network = keyword_plan_network.GOOGLE_SEARCH
134+
keyword_plan_campaign.keyword_plan_network = network
135+
136+
geo_target = client.get_type('KeywordPlanGeoTarget', version='v1')
137+
# Constant for U.S. Other geo target constants can be referenced here:
138+
# https://developers.google.com/adwords/api/docs/appendix/geotargeting
139+
geo_target.geo_target_constant.value = 'geoTargetConstants/2840'
140+
keyword_plan_campaign.geo_targets.extend([geo_target])
141+
142+
language = client.get_type('StringValue', version='v1')
143+
# Constant for English
144+
language.value = 'languageConstants/1000'
145+
keyword_plan_campaign.language_constants.extend([language])
146+
147+
keyword_plan_campaign_service = client.get_service(
148+
'KeywordPlanCampaignService', version='v1')
149+
response = keyword_plan_campaign_service.mutate_keyword_plan_campaigns(
150+
customer_id, [operation])
151+
152+
resource_name = response.results[0].resource_name
153+
154+
print('Created keyword plan campaign with resource name: {}'.format(
155+
resource_name))
156+
157+
return resource_name
158+
159+
160+
def create_keyword_plan_ad_group(client, customer_id, keyword_plan_campaign):
161+
"""Adds a keyword plan ad group to the given keyword plan campaign.
162+
163+
Args:
164+
client: An initialized instance of GoogleAdsClient
165+
customer_id: A str of the customer_id to use in requests.
166+
keyword_plan_campaign: A str of the keyword plan campaign resource_name
167+
this keyword plan ad group should be attributed to.
168+
169+
Returns:
170+
A str of the resource_name for the newly created keyword plan ad group.
171+
172+
Raises:
173+
GoogleAdsException: If an error is returned from the API.
174+
"""
175+
operation = client.get_type('KeywordPlanAdGroupOperation', version='v1')
176+
keyword_plan_ad_group = operation.create
177+
178+
keyword_plan_ad_group.name.value = 'Keyword plan ad group {}'.format(
179+
uuid.uuid4())
180+
keyword_plan_ad_group.cpc_bid_micros.value = 2500000
181+
keyword_plan_ad_group.keyword_plan_campaign.value = keyword_plan_campaign
182+
183+
keyword_plan_ad_group_service = client.get_service(
184+
'KeywordPlanAdGroupService', version='v1')
185+
response = keyword_plan_ad_group_service.mutate_keyword_plan_ad_groups(
186+
customer_id, [operation])
187+
188+
resource_name = response.results[0].resource_name
189+
190+
print('Created keyword plan ad group with resource name: {}'.format(
191+
resource_name))
192+
193+
return resource_name
194+
195+
196+
def create_keyword_plan_keywords(client, customer_id, plan_ad_group):
197+
"""Adds keyword plan keywords to the given keyword plan ad group.
198+
199+
Args:
200+
client: An initialized instance of GoogleAdsClient
201+
customer_id: A str of the customer_id to use in requests.
202+
keyword_plan_ad_group: A str of the keyword plan ad group resource_name
203+
these keyword plan keywords should be attributed to.
204+
205+
Raises:
206+
GoogleAdsException: If an error is returned from the API.
207+
"""
208+
match_types = client.get_type('KeywordMatchTypeEnum', version='v1')
209+
210+
keyword_plan_keyword1 = client.get_type('KeywordPlanKeyword', version='v1')
211+
keyword_plan_keyword1.text.value = 'mars cruise'
212+
keyword_plan_keyword1.cpc_bid_micros.value = 2000000
213+
keyword_plan_keyword1.match_type = match_types.BROAD
214+
keyword_plan_keyword1.keyword_plan_ad_group.value = plan_ad_group
215+
216+
keyword_plan_keyword2 = client.get_type('KeywordPlanKeyword', version='v1')
217+
keyword_plan_keyword2.text.value = 'cheap cruise'
218+
keyword_plan_keyword2.cpc_bid_micros.value = 1500000
219+
keyword_plan_keyword2.match_type = match_types.PHRASE
220+
keyword_plan_keyword2.keyword_plan_ad_group.value = plan_ad_group
221+
222+
keyword_plan_keyword3 = client.get_type('KeywordPlanKeyword', version='v1')
223+
keyword_plan_keyword3.text.value = 'jupiter cruise'
224+
keyword_plan_keyword3.cpc_bid_micros.value = 1990000
225+
keyword_plan_keyword3.match_type = match_types.EXACT
226+
keyword_plan_keyword3.keyword_plan_ad_group.value = plan_ad_group
227+
228+
operations = []
229+
for keyword in [keyword_plan_keyword1,
230+
keyword_plan_keyword2,
231+
keyword_plan_keyword3]:
232+
operation = client.get_type('KeywordPlanKeywordOperation', version='v1')
233+
operation.create.CopyFrom(keyword)
234+
operations.append(operation)
235+
236+
keyword_plan_keyword_service = client.get_service(
237+
'KeywordPlanKeywordService', version='v1')
238+
response = keyword_plan_keyword_service.mutate_keyword_plan_keywords(
239+
customer_id, operations)
240+
241+
for result in response.results:
242+
print('Created keyword plan keyword with resource name: {}'.format(
243+
result.resource_name))
244+
245+
246+
def create_keyword_plan_negative_keywords(client, customer_id, plan_campaign):
247+
"""Adds a keyword plan negative keyword to the given keyword plan campaign.
248+
249+
Args:
250+
client: An initialized instance of GoogleAdsClient
251+
customer_id: A str of the customer_id to use in requests.
252+
keyword_plan_campaign: A str of the keyword plan campaign resource_name
253+
this keyword plan negative keyword should be attributed to.
254+
255+
Raises:
256+
GoogleAdsException: If an error is returned from the API.
257+
"""
258+
match_types = client.get_type('KeywordMatchTypeEnum', version='v1')
259+
operation = client.get_type('KeywordPlanNegativeKeywordOperation',
260+
version='v1')
261+
keyword_plan_negative_keyword = operation.create
262+
263+
keyword_plan_negative_keyword.text.value = 'moon walk'
264+
keyword_plan_negative_keyword.match_type = match_types.BROAD
265+
keyword_plan_negative_keyword.keyword_plan_campaign.value = plan_campaign
266+
267+
keyword_plan_negative_keyword_service = client.get_service(
268+
'KeywordPlanNegativeKeywordService', version='v1')
269+
response = (keyword_plan_negative_keyword_service
270+
.mutate_keyword_plan_negative_keywords(
271+
customer_id, [operation]))
272+
273+
print('Created keyword plan negative keyword with resource name: {}'.format(
274+
response.results[0].resource_name))
275+
276+
277+
if __name__ == '__main__':
278+
# GoogleAdsClient will read the google-ads.yaml configuration file in the
279+
# home directory if none is specified.
280+
google_ads_client = GoogleAdsClient.load_from_storage()
281+
282+
parser = argparse.ArgumentParser(
283+
description='Creates a keyword plan for specified customer.')
284+
# The following argument(s) should be provided to run the example.
285+
parser.add_argument('-c', '--customer_id', type=six.text_type,
286+
required=True, help='The Google Ads customer ID.')
287+
args = parser.parse_args()
288+
289+
main(google_ads_client, args.customer_id)

‎examples/planning/generate_forecast_metrics.py‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# Copyright 2019 Google LLC
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# https://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
"""This example generates forecast metrics for a keyword plan.
15+
16+
To create a keyword plan, run the add_keyword_plan.py example.
17+
"""
18+
19+
from __future__ import absolute_import
20+
21+
import argparse
22+
import six
23+
import sys
24+
25+
from google.ads.google_ads.client import GoogleAdsClient
26+
from google.ads.google_ads.errors import GoogleAdsException
27+
28+
29+
def main(client, customer_id, keyword_plan_id):
30+
keyword_plan_service = client.get_service('KeywordPlanService')
31+
resource_name = keyword_plan_service.keyword_plan_path(customer_id,
32+
keyword_plan_id)
33+
34+
try:
35+
response = keyword_plan_service.generate_forecast_metrics(resource_name)
36+
except GoogleAdsException as ex:
37+
print('Request with ID "{}" failed with status "%s" and includes the '
38+
'following errors:'.format(ex.request_id, ex.error.code().name))
39+
for error in ex.failure.errors:
40+
print('\tError with message "{}".'.format(error.message))
41+
if error.location:
42+
for field_path_element in error.location.field_path_elements:
43+
print('\t\tOn field: {}'.format(field_path_element.field_name))
44+
sys.exit(1)
45+
46+
for i, forecast in enumerate(response.keyword_forecasts):
47+
print('#{} Keyword ID: {}'.format(i + 1,
48+
forecast.keyword_plan_ad_group_keyword.value))
49+
50+
metrics = forecast.keyword_forecast
51+
52+
click_val = metrics.clicks.value
53+
clicks = '{:.2f}'.format(click_val) if click_val else 'unspecified'
54+
print('Estimated daily clicks: {}'.format(clicks))
55+
56+
imp_val = metrics.impressions.value
57+
impressions = '{:.2f}'.format(imp_val) if imp_val else 'unspecified'
58+
print('Estimated daily impressions: {}'.format(impressions))
59+
60+
cpc_val = metrics.average_cpc.value
61+
cpc = '{:.2f}'.format(cpc_val) if cpc_val else 'unspecified'
62+
print('Estimated average cpc: {}\n'.format(cpc))
63+
64+
65+
if __name__ == '__main__':
66+
# GoogleAdsClient will read the google-ads.yaml configuration file in the
67+
# home directory if none is specified.
68+
google_ads_client = GoogleAdsClient.load_from_storage()
69+
70+
parser = argparse.ArgumentParser(
71+
description='Generates forecast metrics for a keyword plan.')
72+
# The following argument(s) should be provided to run the example.
73+
parser.add_argument('-c', '--customer_id', type=six.text_type,
74+
required=True, help='The Google Ads customer ID.')
75+
parser.add_argument('-k', '--keyword_plan_id', type=six.text_type,
76+
required=True, help='A Keyword Plan ID.')
77+
args = parser.parse_args()
78+
79+
main(google_ads_client, args.customer_id, args.keyword_plan_id)

0 commit comments

Comments
 (0)