The code samples below provide examples of common optimization functions using the AdWords API. Client Library.
Get keyword traffic estimates
<?php
/**
* 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.
*/
namespace Google\AdsApi\Examples\AdWords\v201809\Optimization;
require __DIR__ . '/../../../../vendor/autoload.php';
use Google\AdsApi\AdWords\AdWordsServices;
use Google\AdsApi\AdWords\AdWordsSession;
use Google\AdsApi\AdWords\AdWordsSessionBuilder;
use Google\AdsApi\AdWords\v201809\cm\Keyword;
use Google\AdsApi\AdWords\v201809\cm\KeywordMatchType;
use Google\AdsApi\AdWords\v201809\cm\Language;
use Google\AdsApi\AdWords\v201809\cm\Location;
use Google\AdsApi\AdWords\v201809\cm\Money;
use Google\AdsApi\AdWords\v201809\o\AdGroupEstimateRequest;
use Google\AdsApi\AdWords\v201809\o\CampaignEstimateRequest;
use Google\AdsApi\AdWords\v201809\o\KeywordEstimateRequest;
use Google\AdsApi\AdWords\v201809\o\StatsEstimate;
use Google\AdsApi\AdWords\v201809\o\TrafficEstimatorSelector;
use Google\AdsApi\AdWords\v201809\o\TrafficEstimatorService;
use Google\AdsApi\Common\OAuth2TokenBuilder;
/**
* This example gets traffic estimates for new keywords.
*/
class EstimateKeywordTraffic
{
public static function runExample(
AdWordsServices $adWordsServices,
AdWordsSession $session
) {
$trafficEstimatorService = $adWordsServices->get($session, TrafficEstimatorService::class);
// Create keywords. Up to 2000 keywords can be passed in a single request.
$keywords = [];
$keyword = new Keyword();
$keyword->setText('mars cruise');
$keyword->setMatchType(KeywordMatchType::BROAD);
$keywords[] = $keyword;
$keyword = new Keyword();
$keyword->setText('cheap cruise');
$keyword->setMatchType(KeywordMatchType::PHRASE);
$keywords[] = $keyword;
$keyword = new Keyword();
$keyword->setText('cruise');
$keyword->setMatchType(KeywordMatchType::EXACT);
$keywords[] = $keyword;
// Create a keyword estimate request for each keyword.
$keywordEstimateRequests = [];
foreach ($keywords as $keyword) {
$keywordEstimateRequest = new KeywordEstimateRequest();
$keywordEstimateRequest->setKeyword($keyword);
$keywordEstimateRequests[] = $keywordEstimateRequest;
}
// Negative keywords don't return estimates, but adjust the estimates of the
// other keywords in the hypothetical ad group.
$negativeKeywords = [];
$keyword = new Keyword();
$keyword->setText('moon walk');
$keyword->setMatchType(KeywordMatchType::BROAD);
$negativeKeywords[] = $keyword;
// Create a keyword estimate request for each negative keyword.
foreach ($negativeKeywords as $negativeKeyword) {
$keywordEstimateRequest = new KeywordEstimateRequest();
$keywordEstimateRequest->setKeyword($negativeKeyword);
$keywordEstimateRequest->setIsNegative(true);
$keywordEstimateRequests[] = $keywordEstimateRequest;
}
// Create ad group estimate requests.
$adGroupEstimateRequest = new AdGroupEstimateRequest();
$adGroupEstimateRequest->setKeywordEstimateRequests(
$keywordEstimateRequests
);
$money = new Money();
$money->setMicroAmount(1000000);
$adGroupEstimateRequest->setMaxCpc($money);
// Create campaign estimate requests.
$campaignEstimateRequest = new CampaignEstimateRequest();
$campaignEstimateRequest->setAdGroupEstimateRequests(
[$adGroupEstimateRequest]
);
// Optional: Set additional criteria for filtering estimates.
// See http://code.google.com/apis/adwords/docs/appendix/countrycodes.html
// for a detailed list of country codes.
// Set targeting criteria. Only locations and languages are supported.
$unitedStates = new Location();
$unitedStates->setId(2840);
// See http://code.google.com/apis/adwords/docs/appendix/languagecodes.html
// for a detailed list of language codes.
$english = new Language();
$english->setId(1000);
$campaignEstimateRequest->setCriteria([$unitedStates, $english]);
// Create selector.
$selector = new TrafficEstimatorSelector();
$selector->setCampaignEstimateRequests([$campaignEstimateRequest]);
// Optional: Request a list of campaign level estimates segmented by
// platform.
$selector->setPlatformEstimateRequested(true);
$result = $trafficEstimatorService->get($selector);
$platformEstimates = $result->getCampaignEstimates()[0]->getPlatformEstimates();
if ($platformEstimates !== null) {
foreach ($platformEstimates as $platformEstimate) {
if ($platformEstimate->getMinEstimate() !== null
&& $platformEstimate->getMaxEstimate() !== null) {
printf(
"Results for the platform with ID %d and name '%s':\n",
$platformEstimate->getPlatform()->getId(),
$platformEstimate->getPlatform()->getPlatformName()
);
self::printMeanEstimate(
$platformEstimate->getMinEstimate(),
$platformEstimate->getMaxEstimate()
);
}
}
}
$keywordEstimates = $result->getCampaignEstimates()[0]->getAdGroupEstimates()[0]->getKeywordEstimates();
$estimatesCount = count($keywordEstimates);
for ($i = 0; $i < $estimatesCount; $i++) {
$keywordEstimateRequest = $keywordEstimateRequests[$i];
// Skip negative keywords, since they don't return estimates.
if ($keywordEstimateRequest->getIsNegative() !== true) {
$keyword = $keywordEstimateRequest->getKeyword();
$keywordEstimate = $keywordEstimates[$i];
if ($keywordEstimate->getMin() !== null
&& $keywordEstimate->getMax() !== null) {
// Print the mean of the min and max values.
printf(
"Results for the keyword with text '%s' and match type '%s':\n",
$keyword->getText(),
$keyword->getMatchType()
);
self::printMeanEstimate(
$keywordEstimate->getMin(),
$keywordEstimate->getMax()
);
}
}
}
}
/**
* Prints estimated average CPC, ad position, daily clicks, and daily costs
* between the provided lower bound and upper bound of estimated stats.
*
* @param StatsEstimate $minEstimate the lower bound on the estimated stats
* @param StatsEstimate $maxEstimate the upper bound on the estimated stats
*/
private static function printMeanEstimate(
StatsEstimate $minEstimate,
StatsEstimate $maxEstimate
) {
$meanAverageCpc = self::calculateMeanMicroAmount(
$minEstimate->getAverageCpc(),
$maxEstimate->getAverageCpc()
);
$meanAveragePosition = self::calculateMean(
$minEstimate->getAveragePosition(),
$maxEstimate->getAveragePosition()
);
$meanClicks = self::calculateMean(
$minEstimate->getClicksPerDay(),
$maxEstimate->getClicksPerDay()
);
$meanTotalCost = self::calculateMeanMicroAmount(
$minEstimate->getTotalCost(),
$maxEstimate->getTotalCost()
);
printf(
" Estimated average CPC: %s\n",
self::formatMean($meanAverageCpc)
);
printf(
" Estimated ad position: %s\n",
self::formatMean($meanAveragePosition)
);
printf(" Estimated daily clicks: %s\n", self::formatMean($meanClicks));
printf(
" Estimated daily cost: %s\n\n",
self::formatMean($meanTotalCost)
);
}
/**
* Returns the mean of the two numbers if neither is null, else returns null.
*/
private static function calculateMean($min, $max)
{
if ($min === null || $max === null) {
return null;
}
return ($min + $max) / 2;
}
/**
* Returns the mean of the two object's microAmounts if neither is null, else
* returns null.
*/
private static function calculateMeanMicroAmount($min, $max)
{
if ($min === null || $max === null) {
return null;
}
if ($min->getMicroAmount() === null
|| $max->getMicroAmount() === null) {
return null;
}
return ($min->getMicroAmount() + $max->getMicroAmount()) / 2;
}
/**
* Returns a formatted version of the mean value, handling nulls.
*/
private static function formatMean($mean)
{
if ($mean === null) {
return 'null';
}
return sprintf("%.2f", $mean);
}
public static function main()
{
// Generate a refreshable OAuth2 credential for authentication.
$oAuth2Credential = (new OAuth2TokenBuilder())->fromFile()->build();
// Construct an API session configured from a properties file and the
// OAuth2 credentials above.
$session = (new AdWordsSessionBuilder())->fromFile()->withOAuth2Credential($oAuth2Credential)->build();
self::runExample(new AdWordsServices(), $session);
}
}
EstimateKeywordTraffic::main();
Get all mobile bid modifier landscapes for a campaign
<?php
/**
* 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.
*/
namespace Google\AdsApi\Examples\AdWords\v201809\Optimization;
require __DIR__ . '/../../../../vendor/autoload.php';
use Google\AdsApi\AdWords\AdWordsServices;
use Google\AdsApi\AdWords\AdWordsSession;
use Google\AdsApi\AdWords\AdWordsSessionBuilder;
use Google\AdsApi\AdWords\v201809\cm\DataService;
use Google\AdsApi\AdWords\v201809\cm\Paging;
use Google\AdsApi\AdWords\v201809\cm\Predicate;
use Google\AdsApi\AdWords\v201809\cm\PredicateOperator;
use Google\AdsApi\AdWords\v201809\cm\Selector;
use Google\AdsApi\Common\OAuth2TokenBuilder;
/**
* This example gets all available campaign mobile bid modifier landscapes
* for a given campaign.
* To get campaigns, run BasicOperations/GetCampaigns.php.
*/
class GetCampaignCriterionBidModifierSimulations
{
const CAMPAIGN_ID = 'INSERT_CAMPAIGN_ID_HERE';
const PAGE_SIZE = 100;
public static function runExample(
AdWordsServices $adWordsServices,
AdWordsSession $session,
$campaignId
) {
$dataService = $adWordsServices->get($session, DataService::class);
// Create a selector to select all campaign criterion bid modifiers for the
// specified campaign.
$selector = new Selector();
$selector->setFields(
[
'BidModifier',
'CampaignId',
'CriterionId',
'StartDate',
'EndDate',
'LocalClicks',
'LocalCost',
'LocalImpressions',
'TotalLocalClicks',
'TotalLocalCost',
'TotalLocalImpressions',
'RequiredBudget'
]
);
$selector->setPredicates(
[new Predicate('CampaignId', PredicateOperator::IN, [$campaignId])]
);
$selector->setPaging(new Paging(0, self::PAGE_SIZE));
// Display bid landscapes.
$landscapePointsInPreviousPage = 0;
$startIndex = 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.
$startIndex += $landscapePointsInPreviousPage;
$selector->getPaging()->setStartIndex($startIndex);
// Reset the count of landscape points in preparation for processing the
// next page.
$landscapePointsInPreviousPage = 0;
// Retrieve campaign criterion bid modifiers one page at a time,
// continuing to request pages until all of them have been retrieved.
$page = $dataService->getCampaignCriterionBidLandscape($selector);
// Print out some information for each campaign criterion bid modifier.
if ($page->getEntries() !== null) {
foreach ($page->getEntries() as $bidModifierLandscape) {
printf(
"Found campaign-level criterion bid modifier landscapes for"
. " criterion with ID %d, start date '%s', end date '%s', and landscape points:\n",
$bidModifierLandscape->getCriterionId(),
$bidModifierLandscape->getStartDate(),
$bidModifierLandscape->getEndDate()
);
$landscapePointsInPreviousPage = count($bidModifierLandscape->getLandscapePoints());
foreach ($bidModifierLandscape->getLandscapePoints() as $landscapePoint) {
printf(
" bid modifier: %.2f => clicks: %d, cost: %d, "
. "impressions: %d, total clicks: %d, total cost: %d, "
. "total impressions: %d, and required budget: %d\n",
$landscapePoint->getBidModifier(),
$landscapePoint->getClicks(),
$landscapePoint->getCost()->getMicroAmount(),
$landscapePoint->getImpressions(),
$landscapePoint->getTotalLocalClicks(),
$landscapePoint->getTotalLocalCost()->getMicroAmount(),
$landscapePoint->getTotalLocalImpressions(),
$landscapePoint->getRequiredBudget()->getMicroAmount()
);
}
print "\n";
}
}
} while ($landscapePointsInPreviousPage >= self::PAGE_SIZE);
}
public static function main()
{
// Generate a refreshable OAuth2 credential for authentication.
$oAuth2Credential = (new OAuth2TokenBuilder())->fromFile()->build();
// Construct an API session configured from a properties file and the
// OAuth2 credentials above.
$session = (new AdWordsSessionBuilder())->fromFile()->withOAuth2Credential($oAuth2Credential)->build();
self::runExample(
new AdWordsServices(),
$session,
intval(self::CAMPAIGN_ID)
);
}
}
GetCampaignCriterionBidModifierSimulations::main();
Get a bid landscape for an ad group and criterion
<?php
/**
* 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.
*/
namespace Google\AdsApi\Examples\AdWords\v201809\Optimization;
require __DIR__ . '/../../../../vendor/autoload.php';
use Google\AdsApi\AdWords\AdWordsServices;
use Google\AdsApi\AdWords\AdWordsSession;
use Google\AdsApi\AdWords\AdWordsSessionBuilder;
use Google\AdsApi\AdWords\Query\v201809\ServiceQueryBuilder;
use Google\AdsApi\AdWords\v201809\cm\DataService;
use Google\AdsApi\AdWords\v201809\cm\Paging;
use Google\AdsApi\AdWords\v201809\cm\Predicate;
use Google\AdsApi\AdWords\v201809\cm\PredicateOperator;
use Google\AdsApi\AdWords\v201809\cm\Selector;
use Google\AdsApi\Common\OAuth2TokenBuilder;
/**
* This example gets all available keyword bid simulations within an ad group.
* To get ad groups, run BasicOperation/GetAdGroups.php.
*/
class GetKeywordBidSimulations
{
const AD_GROUP_ID = 'INSERT_AD_GROUP_ID_HERE';
const PAGE_SIZE = 100;
public static function runExample(
AdWordsServices $adWordsServices,
AdWordsSession $session,
$adGroupId
) {
$dataService = $adWordsServices->get($session, DataService::class);
// Create a query to select all keyword bid simulations for the
// specified ad group.
$query = (new ServiceQueryBuilder())
->select([
'AdGroupId',
'CriterionId',
'StartDate',
'EndDate',
'Bid',
'BiddableConversions',
'BiddableConversionsValue',
'LocalClicks',
'LocalCost',
'LocalImpressions'
])
->where('AdGroupId')->in([$adGroupId])
->limit(0, self::PAGE_SIZE)
->build();
// Display bid landscapes.
do {
if (isset($fetchedPage)) {
// Advance the paging offset in subsequent iterations only.
$query->nextPage();
}
// Retrieve keyword bid simulations one page at a time, continuing
// to request pages until all of them have been retrieved.
$fetchedPage = $dataService->queryCriterionBidLandscape(
sprintf('%s', $query)
);
// Print out some information for each bid landscape.
if ($fetchedPage->getEntries() !== null) {
foreach ($fetchedPage->getEntries() as $bidLandscape) {
printf(
"Found a criterion bid landscape with ad group ID %d," .
" criterion ID %d, start date '%s', end date '%s'," .
" and landscape points:%s",
$bidLandscape->getAdGroupId(),
$bidLandscape->getCriterionId(),
$bidLandscape->getStartDate(),
$bidLandscape->getEndDate(),
PHP_EOL
);
foreach ($bidLandscape->getLandscapePoints() as
$bidLandscapePoint) {
printf(
" bid: %d => clicks: %d, cost: %d, impressions: %d"
. ", biddable conversions: %.2f, biddable "
. "conversions value: %.2f%s",
$bidLandscapePoint->getBid()->getMicroAmount(),
$bidLandscapePoint->getClicks(),
$bidLandscapePoint->getCost()->getMicroAmount(),
$bidLandscapePoint->getImpressions(),
$bidLandscapePoint->getBiddableConversions(),
$bidLandscapePoint->getBiddableConversionsValue(),
PHP_EOL
);
}
print PHP_EOL;
}
}
} while ($query->hasNext($fetchedPage));
}
public static function main()
{
// Generate a refreshable OAuth2 credential for authentication.
$oAuth2Credential = (new OAuth2TokenBuilder())->fromFile()->build();
// Construct an API session configured from a properties file and the
// OAuth2 credentials above.
$session = (new AdWordsSessionBuilder())
->fromFile()->withOAuth2Credential($oAuth2Credential)->build();
self::runExample(
new AdWordsServices(),
$session,
intval(self::AD_GROUP_ID)
);
}
}
GetKeywordBidSimulations::main();
Get keywords related to a seed keyword
<?php
/**
* 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.
*/
namespace Google\AdsApi\Examples\AdWords\v201809\Optimization;
require __DIR__ . '/../../../../vendor/autoload.php';
use Google\AdsApi\AdWords\AdWordsServices;
use Google\AdsApi\AdWords\AdWordsSession;
use Google\AdsApi\AdWords\AdWordsSessionBuilder;
use Google\AdsApi\AdWords\v201809\cm\Language;
use Google\AdsApi\AdWords\v201809\cm\NetworkSetting;
use Google\AdsApi\AdWords\v201809\cm\Paging;
use Google\AdsApi\AdWords\v201809\o\AttributeType;
use Google\AdsApi\AdWords\v201809\o\IdeaType;
use Google\AdsApi\AdWords\v201809\o\LanguageSearchParameter;
use Google\AdsApi\AdWords\v201809\o\NetworkSearchParameter;
use Google\AdsApi\AdWords\v201809\o\RelatedToQuerySearchParameter;
use Google\AdsApi\AdWords\v201809\o\RequestType;
use Google\AdsApi\AdWords\v201809\o\SeedAdGroupIdSearchParameter;
use Google\AdsApi\AdWords\v201809\o\TargetingIdeaSelector;
use Google\AdsApi\AdWords\v201809\o\TargetingIdeaService;
use Google\AdsApi\Common\OAuth2TokenBuilder;
use Google\AdsApi\Common\Util\MapEntries;
/**
* This example gets keyword ideas related to a seed keyword.
*/
class GetKeywordIdeas
{
// If you do not want to use an existing ad group to seed your request, you
// can set this to null.
const AD_GROUP_ID = 'INSERT_AD_GROUP_ID_HERE';
const PAGE_LIMIT = 500;
public static function runExample(
AdWordsServices $adWordsServices,
AdWordsSession $session,
$adGroupId
) {
$targetingIdeaService = $adWordsServices->get($session, TargetingIdeaService::class);
// Create selector.
$selector = new TargetingIdeaSelector();
$selector->setRequestType(RequestType::IDEAS);
$selector->setIdeaType(IdeaType::KEYWORD);
$selector->setRequestedAttributeTypes(
[
AttributeType::KEYWORD_TEXT,
AttributeType::SEARCH_VOLUME,
AttributeType::AVERAGE_CPC,
AttributeType::COMPETITION,
AttributeType::CATEGORY_PRODUCTS_AND_SERVICES
]
);
$paging = new Paging();
$paging->setStartIndex(0);
$paging->setNumberResults(10);
$selector->setPaging($paging);
$searchParameters = [];
// Create related to query search parameter.
$relatedToQuerySearchParameter = new RelatedToQuerySearchParameter();
$relatedToQuerySearchParameter->setQueries(
[
'bakery',
'pastries',
'birthday cake'
]
);
$searchParameters[] = $relatedToQuerySearchParameter;
// Create language search parameter (optional).
// The ID can be found in the documentation:
// https://developers.google.com/adwords/api/docs/appendix/languagecodes
$languageParameter = new LanguageSearchParameter();
$english = new Language();
$english->setId(1000);
$languageParameter->setLanguages([$english]);
$searchParameters[] = $languageParameter;
// Create network search parameter (optional).
$networkSetting = new NetworkSetting();
$networkSetting->setTargetGoogleSearch(true);
$networkSetting->setTargetSearchNetwork(false);
$networkSetting->setTargetContentNetwork(false);
$networkSetting->setTargetPartnerSearchNetwork(false);
$networkSearchParameter = new NetworkSearchParameter();
$networkSearchParameter->setNetworkSetting($networkSetting);
$searchParameters[] = $networkSearchParameter;
// Optional: Use an existing ad group to generate ideas.
if (!empty($adGroupId)) {
$seedAdGroupIdSearchParameter = new SeedAdGroupIdSearchParameter();
$seedAdGroupIdSearchParameter->setAdGroupId($adGroupId);
$searchParameters[] = $seedAdGroupIdSearchParameter;
}
$selector->setSearchParameters($searchParameters);
$selector->setPaging(new Paging(0, self::PAGE_LIMIT));
// Get keyword ideas.
$page = $targetingIdeaService->get($selector);
// Print out some information for each targeting idea.
$entries = $page->getEntries();
if ($entries !== null) {
foreach ($entries as $targetingIdea) {
$data = MapEntries::toAssociativeArray($targetingIdea->getData());
$keyword = $data[AttributeType::KEYWORD_TEXT]->getValue();
$searchVolume = ($data[AttributeType::SEARCH_VOLUME]->getValue() !== null)
? $data[AttributeType::SEARCH_VOLUME]->getValue() : 0;
$averageCpc = $data[AttributeType::AVERAGE_CPC]->getValue();
$competition = $data[AttributeType::COMPETITION]->getValue();
$categoryIds = ($data[AttributeType::CATEGORY_PRODUCTS_AND_SERVICES]->getValue() === null)
? $categoryIds = ''
: implode(
', ',
$data[AttributeType::CATEGORY_PRODUCTS_AND_SERVICES]->getValue()
);
printf(
"Keyword with text '%s', average monthly search volume %d, "
. "average CPC %d, and competition %.2f was found with categories: %s\n",
$keyword,
$searchVolume,
($averageCpc === null) ? 0 : $averageCpc->getMicroAmount(),
$competition,
$categoryIds
);
}
}
if (empty($entries)) {
print "No related keywords were found.\n";
}
}
public static function main()
{
// Generate a refreshable OAuth2 credential for authentication.
$oAuth2Credential = (new OAuth2TokenBuilder())->fromFile()->build();
// Construct an API session configured from a properties file and the
// OAuth2 credentials above.
$session = (new AdWordsSessionBuilder())->fromFile()->withOAuth2Credential($oAuth2Credential)->build();
self::runExample(new AdWordsServices(), $session, self::AD_GROUP_ID);
}
}
GetKeywordIdeas::main();