The code samples below provide examples of common optimization functions using the AdWords API. Client Library.
Get keyword traffic estimates
#!/usr/bin/perl -w # # Copyright 2017, Google Inc. All Rights Reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. # # This example gets keyword traffic estimates. use strict; use lib "../../../lib"; use Google::Ads::AdWords::Client; use Google::Ads::AdWords::Logging; use Google::Ads::AdWords::v201809::AdGroupEstimateRequest; use Google::Ads::AdWords::v201809::CampaignEstimateRequest; use Google::Ads::AdWords::v201809::Keyword; use Google::Ads::AdWords::v201809::KeywordEstimateRequest; use Google::Ads::AdWords::v201809::Language; use Google::Ads::AdWords::v201809::Location; use Google::Ads::AdWords::v201809::TrafficEstimatorSelector; use Cwd qw(abs_path); # Example main subroutine. sub estimate_keyword_traffic { my $client = shift; # Create keywords. Refer to the TrafficEstimatorService documentation for # the maximum number of keywords that can be passed in a single request. # https://developers.google.com/adwords/api/docs/reference/latest/TrafficEstimatorService my @keywords = ( Google::Ads::AdWords::v201809::Keyword->new({ text => "mars cruise", matchType => "BROAD" } ), Google::Ads::AdWords::v201809::Keyword->new({ text => "cheap cruise", matchType => "PHRASE" } ), Google::Ads::AdWords::v201809::Keyword->new({ text => "cruise", matchType => "EXACT" })); my @negative_keywords = ( Google::Ads::AdWords::v201809::Keyword->new({ text => "moon walk", matchType => "BROAD" })); # Create a keyword estimate request for each keyword. my @keyword_estimate_requests; foreach my $keyword (@keywords) { push @keyword_estimate_requests, Google::Ads::AdWords::v201809::KeywordEstimateRequest->new( {keyword => $keyword,}); } foreach my $keyword (@negative_keywords) { push @keyword_estimate_requests, Google::Ads::AdWords::v201809::KeywordEstimateRequest->new({ keyword => $keyword, isNegative => 1 }); } # Create ad group estimate requests. my $ad_group_estimate_request = Google::Ads::AdWords::v201809::AdGroupEstimateRequest->new({ keywordEstimateRequests => \@keyword_estimate_requests, maxCpc => Google::Ads::AdWords::v201809::Money->new({microAmount => 1000000})}); my $location = Google::Ads::AdWords::v201809::Location->new({ id => "2840" # US - see http://goo.gl/rlrFr }); my $language = Google::Ads::AdWords::v201809::Language->new({ id => "1000" # en - see http://goo.gl/LvMmS }); # Create campaign estimate requests. my $campaign_estimate_request = Google::Ads::AdWords::v201809::CampaignEstimateRequest->new({ adGroupEstimateRequests => [$ad_group_estimate_request], criteria => [$location, $language]}); # Optional: Request a list of campaign level estimates segmented by platform. my $platform_estimate_request = "1"; # Create selector. my $selector = Google::Ads::AdWords::v201809::TrafficEstimatorSelector->new({ campaignEstimateRequests => [$campaign_estimate_request], platformEstimateRequested => [$platform_estimate_request]}); # Get traffic estimates. my $result = $client->TrafficEstimatorService()->get({selector => $selector}); # Display traffic estimates. if ($result) { my $campaign_estimates = $result->get_campaignEstimates(); if ($campaign_estimates) { # Display the campaign level estimates segmented by platform. foreach my $campaign_estimate (@{$campaign_estimates}) { if ($campaign_estimate->get_platformEstimates()) { foreach my $platform_estimate (@{$campaign_estimate->get_platformEstimates()}) { my $platform_message = sprintf( "Results for the platform with ID: %d and name : %s", $platform_estimate->get_platform()->get_id(), $platform_estimate->get_platform()->get_platformName()); display_mean_estimates( $platform_message, $platform_estimate->get_minEstimate(), $platform_estimate->get_maxEstimate()); } } if ($campaign_estimate->get_adGroupEstimates()) { my $keyword_estimates = $campaign_estimate->get_adGroupEstimates()->[0] ->get_keywordEstimates(); for (my $i = 0 ; $i < scalar(@{$keyword_estimates}) ; $i++) { # Negative keywords don't generate estimates but instead affect # estimates of your other keywords, the following condition just # skips printing out estimates for a negative keyword. if ($keyword_estimate_requests[$i]->get_isNegative()) { next; } my $keyword = $keyword_estimate_requests[$i]->get_keyword(); my $keyword_estimate = $keyword_estimates->[$i]; my $keyword_message = sprintf "Results for the keyword with text '%s' and match type '%s':\n", $keyword->get_text(), $keyword->get_matchType(); display_mean_estimates( $keyword_message, $keyword_estimate->get_min(), $keyword_estimate->get_max()); } } } } } else { print "No traffic estimates were returned.\n"; } return 1; } # Display the mean estimates. sub display_mean_estimates { my ($message, $min_estimate, $max_estimate) = @_; # Find the mean of the min and max values. my $mean_average_cpc = calculate_money_mean($min_estimate->get_averageCpc(), $max_estimate->get_averageCpc()); my $mean_average_position = calculate_mean( $min_estimate->get_averagePosition(), $max_estimate->get_averagePosition()); my $mean_clicks = calculate_mean($min_estimate->get_clicksPerDay(), $max_estimate->get_clicksPerDay()); my $mean_total_cost = calculate_money_mean($min_estimate->get_totalCost(), $max_estimate->get_totalCost()); printf "%s:\n", $message; printf " Estimated average CPC: %.2f\n", $mean_average_cpc; printf " Estimated ad position: %.2f\n", $mean_average_position; printf " Estimated daily clicks: %.2f\n", $mean_clicks; printf " Estimated daily cost: %.2f\n\n", $mean_total_cost; } # Calculates the mean microAmount of two Money objects if neither is # null, else returns NaN. sub calculate_money_mean { my ($min_money, $max_money) = @_; if ($min_money && $max_money) { return calculate_mean($min_money->get_microAmount(), $max_money->get_microAmount()); } return 'NaN'; } # Calculates the mean of two numbers if neither is null, else returns NaN. sub calculate_mean { my ($min, $max) = @_; if (defined($min) && defined($max)) { return ($min + $max) / 2; } return 'NaN'; } # Don't run the example if the file is being included. if (abs_path($0) ne abs_path(__FILE__)) { return 1; } # Log SOAP XML request, response and API errors. Google::Ads::AdWords::Logging::enable_all_logging(); # Get AdWords Client, credentials will be read from ~/adwords.properties. my $client = Google::Ads::AdWords::Client->new({version => "v201809"}); # By default examples are set to die on any server returned fault. $client->set_die_on_faults(1); # Call the example estimate_keyword_traffic($client);
Get all mobile bid modifier landscapes for a campaign
#!/usr/bin/perl -w # # Copyright 2017, Google Inc. All Rights Reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. # # This example gets all available campaign mobile bid modifier landscapes # for a given campaign. # To get campaigns, run basic_operations/get_campaigns.pl. use strict; use lib "../../../lib"; use Google::Ads::AdWords::Client; use Google::Ads::AdWords::Logging; use Google::Ads::AdWords::v201809::OrderBy; use Google::Ads::AdWords::v201809::Paging; use Google::Ads::AdWords::v201809::Predicate; use Google::Ads::AdWords::v201809::Selector; use Cwd qw(abs_path); use constant PAGE_SIZE => 100; # Replace with a valid value of your account. my $campaign_id = "INSERT_CAMPAIGN_ID_HERE"; # Example main subroutine. sub get_campaign_criterion_bid_modifier_simulations { my $client = shift; my $campaign_id = shift; # Create predicates. my $campaign_predicate = Google::Ads::AdWords::v201809::Predicate->new({ field => "CampaignId", operator => "IN", values => [$campaign_id]}); # Create selector. my $paging = Google::Ads::AdWords::v201809::Paging->new({ startIndex => 0, numberResults => PAGE_SIZE }); my $selector = Google::Ads::AdWords::v201809::Selector->new({ fields => [ "BidModifier", "CampaignId", "CriterionId", "StartDate", "EndDate", "LocalClicks", "LocalCost", "LocalImpressions", "TotalLocalClicks", "TotalLocalCost", "TotalLocalImpressions", "RequiredBudget" ], paging => $paging, predicates => [$campaign_predicate]}); # Display bid landscapes. my $landscape_points_in_previous_page = 0; my $start_index = 0; do { # Offset the start index by the number of landscape points in the last # retrieved page, NOT the number of entries (bid landscapes) in the page. $start_index += $landscape_points_in_previous_page; $selector->get_paging()->set_startIndex($start_index); # Reset the count of landscape points in preparation for processing the # next page. $landscape_points_in_previous_page = 0; # Request the next page of bid landscapes. my $page = $client->DataService() ->getCampaignCriterionBidLandscape({serviceSelector => $selector}); if ($page->get_entries()) { foreach my $criterion_bid_landscape (@{$page->get_entries()}) { printf "Found campaign-level criterion bid modifier landscapes for" . " criterion with ID %d, start date '%s', end date '%s', and" . " landscape points:\n", $criterion_bid_landscape->get_criterionId(), $criterion_bid_landscape->get_startDate(), $criterion_bid_landscape->get_endDate(); my @landscape_points = @{$criterion_bid_landscape ->get_landscapePoints()}; foreach my $landscape_point (@landscape_points) { $landscape_points_in_previous_page++; printf " bid modifier: %.2f => clicks: %d, cost: %.0f, " . "impressions: %d, total clicks: %d, total cost: %.0f, " . "total impressions: %d, and required budget: %.0f\n", $landscape_point->get_bidModifier(), $landscape_point->get_clicks(), $landscape_point->get_cost()->get_microAmount(), $landscape_point->get_impressions(), $landscape_point->get_totalLocalClicks(), $landscape_point->get_totalLocalCost()->get_microAmount(), $landscape_point->get_totalLocalImpressions(), $landscape_point->get_requiredBudget()->get_microAmount(); } } } } while ($landscape_points_in_previous_page >= PAGE_SIZE); return 1; } # Don't run the example if the file is being included. if (abs_path($0) ne abs_path(__FILE__)) { return 1; } # Log SOAP XML request, response and API errors. Google::Ads::AdWords::Logging::enable_all_logging(); # Get AdWords Client, credentials will be read from ~/adwords.properties. my $client = Google::Ads::AdWords::Client->new({version => "v201809"}); # By default examples are set to die on any server returned fault. $client->set_die_on_faults(1); # Call the example get_campaign_criterion_bid_modifier_simulations($client, $campaign_id);
Get a bid landscape for an ad group and criterion
#!/usr/bin/perl -w # # Copyright 2017, Google Inc. All Rights Reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. # # This example gets bid landscapes for a keywords. To get keywords, run # basic_operations/get_keywords.pl. use strict; use lib "../../../lib"; use Google::Ads::AdWords::Client; use Google::Ads::AdWords::Logging; use Google::Ads::AdWords::Utilities::ServiceQueryBuilder; use Cwd qw(abs_path); use constant PAGE_SIZE => 100; # Replace with valid values of your account. my $ad_group_id = "INSERT_AD_GROUP_ID_HERE"; my $keyword_id = "INSERT_CRITERION_ID_HERE"; # Example main subroutine. sub get_keyword_bid_simulations { my ($client, $ad_group_id, $keyword_id) = @_; # Create a query to select all keyword bid simulations for the # specified ad group. my $query_builder = Google::Ads::AdWords::Utilities::ServiceQueryBuilder->new( {client => $client}) ->select([ "AdGroupId", "CriterionId", "StartDate", "EndDate", "Bid", "BiddableConversions", "BiddableConversionsValue", "LocalClicks", "LocalCost", "LocalImpressions"]) ->where("AdGroupId")->in([$ad_group_id]) ->where("CriterionId")->in([$keyword_id]) ->limit(0, PAGE_SIZE); # Display bid landscapes. my $landscape_points_in_previous_page = 0; my $page; do { # Offset the start index by the number of landscape points in the last # retrieved page, NOT the number of entries (bid landscapes) in the page. if (defined($page)) { $query_builder->next_page($landscape_points_in_previous_page); } # Reset the count of landscape points in preparation for processing the # next page. $landscape_points_in_previous_page = 0; # Request the next page of bid landscapes. $page = $client->DataService() ->queryCriterionBidLandscape({query => $query_builder->build()}); if ($page->get_entries()) { foreach my $criterion_bid_landscape (@{$page->get_entries()}) { printf "Criterion bid landscape with ad group ID %d, criterion ID " . " %d, start date %s, end date %s, with landscape points:\n", $criterion_bid_landscape->get_adGroupId(), $criterion_bid_landscape->get_criterionId(), $criterion_bid_landscape->get_startDate(), $criterion_bid_landscape->get_endDate(); foreach my $bid_landscape_point ( @{$criterion_bid_landscape->get_landscapePoints()}) { $landscape_points_in_previous_page++; printf " bid: %d => clicks: %d, cost: %d, impressions: %d" . ", biddable conversions: %.2f, biddable " . "conversions value: %.2f\n", $bid_landscape_point->get_bid()->get_microAmount(), $bid_landscape_point->get_clicks(), $bid_landscape_point->get_cost()->get_microAmount(), $bid_landscape_point->get_impressions(), $bid_landscape_point->get_biddableConversions(), $bid_landscape_point->get_biddableConversionsValue(); } printf(" was found."); } } } while ($query_builder->has_next($page, $landscape_points_in_previous_page)); return 1; } # Don't run the example if the file is being included. if (abs_path($0) ne abs_path(__FILE__)) { return 1; } # Log SOAP XML request, response and API errors. Google::Ads::AdWords::Logging::enable_all_logging(); # Get AdWords Client, credentials will be read from ~/adwords.properties. my $client = Google::Ads::AdWords::Client->new({version => "v201809"}); # By default examples are set to die on any server returned fault. $client->set_die_on_faults(1); # Call the example get_keyword_bid_simulations($client, $ad_group_id, $keyword_id);
Get keywords related to a seed keyword
#!/usr/bin/perl -w # # Copyright 2017, Google Inc. All Rights Reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. # # This example gets keywords related to a list of seed keywords. use strict; use lib "../../../lib"; use Google::Ads::AdWords::Client; use Google::Ads::AdWords::Logging; use Google::Ads::AdWords::v201809::Language; use Google::Ads::AdWords::v201809::LanguageSearchParameter; use Google::Ads::AdWords::v201809::NetworkSearchParameter; use Google::Ads::AdWords::v201809::NetworkSetting; use Google::Ads::AdWords::v201809::Paging; use Google::Ads::AdWords::v201809::RelatedToQuerySearchParameter; use Google::Ads::AdWords::v201809::SeedAdGroupIdSearchParameter; use Google::Ads::AdWords::v201809::TargetingIdeaSelector; use Google::Ads::Common::MapUtils; use Cwd qw(abs_path); # Replace with valid values of your account. # If you do not want to use an existing ad group to seed your request, you can # set this to undef. my $ad_group_id = "INSERT_AD_GROUP_ID_HERE"; # Example main subroutine. sub get_keyword_ideas { my ($client, $ad_group_id) = @_; # Create selector. my $selector = Google::Ads::AdWords::v201809::TargetingIdeaSelector->new({ requestType => "IDEAS", ideaType => "KEYWORD" }); $selector->set_requestedAttributeTypes([ "KEYWORD_TEXT", "SEARCH_VOLUME", "AVERAGE_CPC", "COMPETITION", "CATEGORY_PRODUCTS_AND_SERVICES" ]); # Create related to query search parameter. my @search_parameters = (); my $related_to_query_search_parameter = Google::Ads::AdWords::v201809::RelatedToQuerySearchParameter->new( {queries => ["bakery", "pastries", "birthday cake"]}); push @search_parameters, $related_to_query_search_parameter; # Set selector paging (required for targeting idea service). my $paging = Google::Ads::AdWords::v201809::Paging->new({ startIndex => 0, numberResults => 10 }); $selector->set_paging($paging); # Language setting (not-required). # The ID can be found in the documentation: # https://developers.google.com/adwords/api/docs/appendix/languagecodes my $language_english = Google::Ads::AdWords::v201809::Language->new({id => 1000}); my $language_search_parameter = Google::Ads::AdWords::v201809::LanguageSearchParameter->new( {languages => [$language_english]}); push @search_parameters, $language_search_parameter; # Create network search paramter (optional). my $network_setting = Google::Ads::AdWords::v201809::NetworkSetting->new({ targetGoogleSearch => 1, targetSearchNetwork => 0, targetContentNetwork => 0, targetPartnerSearchNetwork => 0 }); my $network_setting_parameter = Google::Ads::AdWords::v201809::NetworkSearchParameter->new( {networkSetting => $network_setting}); push @search_parameters, $network_setting_parameter; # Optional: Use an existing ad group to generate ideas. if ($ad_group_id) { my $seed_ad_group_id_search_parameter = Google::Ads::AdWords::v201809::SeedAdGroupIdSearchParameter->new({ adGroupId => $ad_group_id }); push @search_parameters, $seed_ad_group_id_search_parameter; } $selector->set_searchParameters(\@search_parameters); # Get keyword ideas. my $page = $client->TargetingIdeaService()->get({selector => $selector}); # Display keyword ideas. if ($page->get_entries()) { foreach my $targeting_idea (@{$page->get_entries()}) { my $data = Google::Ads::Common::MapUtils::get_map($targeting_idea->get_data()); my $keyword = $data->{"KEYWORD_TEXT"}->get_value(); my $search_volume = $data->{"SEARCH_VOLUME"}->get_value() ? $data->{"SEARCH_VOLUME"}->get_value() : 0; my $categories = $data->{"CATEGORY_PRODUCTS_AND_SERVICES"}->get_value() ? $data->{"CATEGORY_PRODUCTS_AND_SERVICES"}->get_value() : []; my $average_cpc = $data->{"AVERAGE_CPC"}->get_value()->get_microAmount(); my $competition = $data->{"COMPETITION"}->get_value(); printf "Keyword with text '%s', monthly search volume %d, average CPC" . " %d, and competition %.2f was found with categories: '%s'\n", $keyword, $search_volume, $average_cpc, $competition, join(", ", @{$categories}); } } else { print "No related keywords were found.\n"; } return 1; } # Don't run the example if the file is being included. if (abs_path($0) ne abs_path(__FILE__)) { return 1; } # Log SOAP XML request, response and API errors. Google::Ads::AdWords::Logging::enable_all_logging(); # Get AdWords Client, credentials will be read from ~/adwords.properties. my $client = Google::Ads::AdWords::Client->new({version => "v201809"}); # By default examples are set to die on any server returned fault. $client->set_die_on_faults(1); # Call the example get_keyword_ideas($client, $ad_group_id);