The code samples below provide examples of common reporting functions using the AdWords API. Client Library.
Download a criteria performance report with AWQL
<?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\Reporting;
require __DIR__ . '/../../../../vendor/autoload.php';
use Google\AdsApi\AdWords\AdWordsSession;
use Google\AdsApi\AdWords\AdWordsSessionBuilder;
use Google\AdsApi\AdWords\Query\v201809\ReportQueryBuilder;
use Google\AdsApi\AdWords\Reporting\v201809\DownloadFormat;
use Google\AdsApi\AdWords\Reporting\v201809\ReportDefinitionDateRangeType;
use Google\AdsApi\AdWords\Reporting\v201809\ReportDownloader;
use Google\AdsApi\AdWords\ReportSettingsBuilder;
use Google\AdsApi\AdWords\v201809\cm\ReportDefinitionReportType;
use Google\AdsApi\Common\OAuth2TokenBuilder;
/**
* Downloads CRITERIA_PERFORMANCE_REPORT for the specified client customer ID.
*/
class DownloadCriteriaReportWithAwql
{
public static function runExample(AdWordsSession $session, $reportFormat)
{
// Create report query to get the data for last 7 days.
$query = (new ReportQueryBuilder())
->select([
'CampaignId',
'AdGroupId',
'Id',
'Criteria',
'CriteriaType',
'Impressions',
'Clicks',
'Cost'
])
->from(ReportDefinitionReportType::CRITERIA_PERFORMANCE_REPORT)
->where('Status')->in(['ENABLED', 'PAUSED'])
->duringDateRange(ReportDefinitionDateRangeType::LAST_7_DAYS)
->build();
// Download report as a string.
$reportDownloader = new ReportDownloader($session);
// Optional: If you need to adjust report settings just for this one
// request, you can create and supply the settings override here.
// Otherwise, default values from the configuration
// file (adsapi_php.ini) are used.
$reportSettingsOverride = (new ReportSettingsBuilder())
->includeZeroImpressions(false)
->build();
$reportDownloadResult = $reportDownloader->downloadReportWithAwql(
sprintf('%s', $query),
$reportFormat,
$reportSettingsOverride
);
print "Report was downloaded and printed below:\n";
print $reportDownloadResult->getAsString();
}
public static function main()
{
// Generate a refreshable OAuth2 credential for authentication.
$oAuth2Credential = (new OAuth2TokenBuilder())->fromFile()->build();
// See: AdWordsSessionBuilder for setting a client customer ID that is
// different from that specified in your adsapi_php.ini file.
// Construct an API session configured from a properties file and the
// OAuth2 credentials above.
$session = (new AdWordsSessionBuilder())
->fromFile()
->withOAuth2Credential($oAuth2Credential)
->build();
self::runExample($session, DownloadFormat::CSV);
}
}
DownloadCriteriaReportWithAwql::main();
Download a criteria performance report using selectors
<?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\Reporting;
require __DIR__ . '/../../../../vendor/autoload.php';
use Google\AdsApi\AdWords\AdWordsSession;
use Google\AdsApi\AdWords\AdWordsSessionBuilder;
use Google\AdsApi\AdWords\Reporting\v201809\DownloadFormat;
use Google\AdsApi\AdWords\Reporting\v201809\ReportDefinition;
use Google\AdsApi\AdWords\Reporting\v201809\ReportDefinitionDateRangeType;
use Google\AdsApi\AdWords\Reporting\v201809\ReportDownloader;
use Google\AdsApi\AdWords\ReportSettingsBuilder;
use Google\AdsApi\AdWords\v201809\cm\Predicate;
use Google\AdsApi\AdWords\v201809\cm\PredicateOperator;
use Google\AdsApi\AdWords\v201809\cm\ReportDefinitionReportType;
use Google\AdsApi\AdWords\v201809\cm\Selector;
use Google\AdsApi\Common\OAuth2TokenBuilder;
/**
* Downloads CRITERIA_PERFORMANCE_REPORT for the specified client customer ID.
*/
class DownloadCriteriaReportWithSelector
{
public static function runExample(AdWordsSession $session, $filePath)
{
// Create selector.
$selector = new Selector();
$selector->setFields(
[
'CampaignId',
'AdGroupId',
'Id',
'Criteria',
'CriteriaType',
'Impressions',
'Clicks',
'Cost'
]
);
// Use a predicate to filter out paused criteria (this is optional).
$selector->setPredicates(
[
new Predicate('Status', PredicateOperator::NOT_IN, ['PAUSED'])
]
);
// Create report definition.
$reportDefinition = new ReportDefinition();
$reportDefinition->setSelector($selector);
$reportDefinition->setReportName(
'Criteria performance report #' . uniqid()
);
$reportDefinition->setDateRangeType(
ReportDefinitionDateRangeType::LAST_7_DAYS
);
$reportDefinition->setReportType(
ReportDefinitionReportType::CRITERIA_PERFORMANCE_REPORT
);
$reportDefinition->setDownloadFormat(DownloadFormat::CSV);
// Download report.
$reportDownloader = new ReportDownloader($session);
// Optional: If you need to adjust report settings just for this one
// request, you can create and supply the settings override here. Otherwise,
// default values from the configuration file (adsapi_php.ini) are used.
$reportSettingsOverride = (new ReportSettingsBuilder())->includeZeroImpressions(false)->build();
$reportDownloadResult = $reportDownloader->downloadReport(
$reportDefinition,
$reportSettingsOverride
);
$reportDownloadResult->saveToFile($filePath);
printf(
"Report with name '%s' was downloaded to '%s'.\n",
$reportDefinition->getReportName(),
$filePath
);
}
public static function main()
{
// Generate a refreshable OAuth2 credential for authentication.
$oAuth2Credential = (new OAuth2TokenBuilder())->fromFile()->build();
// See: AdWordsSessionBuilder for setting a client customer ID that is
// different from that specified in your adsapi_php.ini file.
// Construct an API session configured from a properties file and the
// OAuth2 credentials above.
$session = (new AdWordsSessionBuilder())->fromFile()->withOAuth2Credential($oAuth2Credential)->build();
$filePath = sprintf(
'%s.csv',
tempnam(sys_get_temp_dir(), 'criteria-report-')
);
self::runExample($session, $filePath);
}
}
DownloadCriteriaReportWithSelector::main();
Get the report fields from a report
<?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\Reporting;
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\ReportDefinitionReportType;
use Google\AdsApi\AdWords\v201809\cm\ReportDefinitionService;
use Google\AdsApi\Common\OAuth2TokenBuilder;
/**
* This example gets the fields available in a campaign report.
*/
class GetReportFields
{
const PAGE_LIMIT = 500;
public static function runExample(
AdWordsServices $adWordsServices,
AdWordsSession $session
) {
$reportDefinitionService = $adWordsServices->get($session, ReportDefinitionService::class);
// The type of the report to get fields for.
$reportType = ReportDefinitionReportType::CAMPAIGN_PERFORMANCE_REPORT;
// Get report fields of the report type.
$reportDefinitionFields = $reportDefinitionService->getReportFields($reportType);
printf(
"The report type '%s' contains the following fields:\n",
$reportType
);
foreach ($reportDefinitionFields as $reportDefinitionField) {
printf(
' %s (%s)',
$reportDefinitionField->getFieldName(),
$reportDefinitionField->getFieldType()
);
if ($reportDefinitionField->getEnumValues() !== null) {
printf(
' := [%s]',
implode(', ', $reportDefinitionField->getEnumValues())
);
}
print "\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);
}
}
GetReportFields::main();
Download a report for multiple accounts
<?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\Reporting;
require __DIR__ . '/../../../../vendor/autoload.php';
use Google\AdsApi\AdWords\AdWordsServices;
use Google\AdsApi\AdWords\AdWordsSession;
use Google\AdsApi\AdWords\AdWordsSessionBuilder;
use Google\AdsApi\AdWords\Reporting\v201809\DownloadFormat;
use Google\AdsApi\AdWords\Reporting\v201809\ReportDefinition;
use Google\AdsApi\AdWords\Reporting\v201809\ReportDefinitionDateRangeType;
use Google\AdsApi\AdWords\Reporting\v201809\ReportDownloader;
use Google\AdsApi\AdWords\ReportSettingsBuilder;
use Google\AdsApi\AdWords\v201809\cm\ApiException;
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\ReportDefinitionReportType;
use Google\AdsApi\AdWords\v201809\cm\Selector;
use Google\AdsApi\AdWords\v201809\mcm\ManagedCustomerService;
use Google\AdsApi\Common\OAuth2TokenBuilder;
/**
* This example gets and downloads an Ad Hoc report from an XML report
* definition for all accounts directly under a manager account.
* This example should be run against an AdWords manager account.
*
* Although the example's name is `ParallelReportDownload`, it doesn't download
* reports in parallel as this client library doesn't support multithreading.
* It is named so to be consistent with other client libraries.
*/
class ParallelReportDownload
{
// Timeout between retries in seconds.
const BACKOFF_FACTOR = 5;
// Maximum number of retries for 500 errors.
const MAX_RETRIES = 5;
// The number of entries per page of the results.
const PAGE_LIMIT = 500;
public static function runExample(
AdWordsServices $adWordsServices,
AdWordsSessionBuilder $sessionBuilder,
$reportDir
) {
// Construct an API session for the client customer ID specified in the
// configuration file.
$session = $sessionBuilder->build();
// Create selector.
$selector = new Selector();
$selector->setFields(
['CampaignId', 'AdGroupId', 'Impressions', 'Clicks', 'Cost']
);
// Create report definition.
$reportDefinition = new ReportDefinition();
$reportDefinition->setSelector($selector);
$reportDefinition->setReportName('Custom ADGROUP_PERFORMANCE_REPORT');
$reportDefinition->setDateRangeType(
ReportDefinitionDateRangeType::LAST_7_DAYS
);
$reportDefinition->setReportType(
ReportDefinitionReportType::ADGROUP_PERFORMANCE_REPORT
);
$reportDefinition->setDownloadFormat(DownloadFormat::CSV);
$customerIds = self::getAllManagedCustomerIds($adWordsServices, $session);
printf(
"Downloading reports for %d managed customers.\n",
count($customerIds)
);
$successfulReports = [];
$failedReports = [];
foreach ($customerIds as $customerId) {
$filePath = sprintf(
'%s%sadgroup_%d.csv',
$reportDir,
DIRECTORY_SEPARATOR,
$customerId
);
// Construct an API session for the specified client customer ID.
$session = $sessionBuilder->withClientCustomerId($customerId)->build();
$reportDownloader = new ReportDownloader($session);
$retryCount = 0;
$doContinue = true;
do {
$retryCount++;
try {
// Optional: If you need to adjust report settings just for this one
// request, you can create and supply the settings override here.
// Otherwise, default values from the configuration file
// (adsapi_php.ini) are used.
$reportSettingsOverride = (new ReportSettingsBuilder())->includeZeroImpressions(false)->build();
$reportDownloadResult = $reportDownloader->downloadReport(
$reportDefinition,
$reportSettingsOverride
);
$reportDownloadResult->saveToFile($filePath);
printf(
"Report for client customer ID %d successfully downloaded to: %s\n",
$customerId,
$filePath
);
$successfulReports[$customerId] = $filePath;
$doContinue = false;
} catch (ApiException $e) {
printf(
"Report attempt #%d for client customer ID %d was not downloaded due to: %s\n",
$retryCount,
$customerId,
$e->getMessage()
);
// If this is a server error, retry up to the defined maximum number
// of retries.
if ($e->getErrors() === null && $retryCount < self::MAX_RETRIES) {
$sleepTime = $retryCount * self::BACKOFF_FACTOR;
printf(
"Sleeping %d seconds before retrying report for client customer ID %d.\n",
$sleepTime,
$customerId
);
sleep($sleepTime);
} else {
printf(
"Report request failed for client customer ID %d.\n",
$customerId
);
$failedReports[$customerId] = $filePath;
$doContinue = false;
}
}
} while ($doContinue === true);
}
print "All downloads completed. Results:\n";
print "Successful reports:\n";
foreach ($successfulReports as $customerId => $filePath) {
printf("\tClient ID %d => '%s'\n", $customerId, $filePath);
}
print "Failed reports:\n";
foreach ($failedReports as $customerId => $filePath) {
printf("\tClient ID %d => '%s'\n", $customerId, $filePath);
}
print "End of results.\n";
}
/**
* Retrieves all the customer IDs under a manager account.
*
* To set clientCustomerId to any manager account you want to get
* reports for its client accounts, use `AdWordsSessionBuilder` to
* create new session.
*/
private static function getAllManagedCustomerIds(
AdWordsServices $adWordsServices,
AdWordsSession $session
) {
$managedCustomerService = $adWordsServices->get($session, ManagedCustomerService::class);
$selector = new Selector();
$selector->setFields(['CustomerId']);
$selector->setPaging(new Paging(0, self::PAGE_LIMIT));
$selector->setPredicates(
[
new Predicate(
'CanManageClients',
PredicateOperator::EQUALS,
['false']
)
]
);
$customerIds = [];
$totalNumEntries = 0;
do {
$page = $managedCustomerService->get($selector);
if ($page->getEntries() !== null) {
$totalNumEntries = $page->getTotalNumEntries();
foreach ($page->getEntries() as $customer) {
$customerIds[] = $customer->getCustomerId();
}
}
$selector->getPaging()->setStartIndex(
$selector->getPaging()->getStartIndex() + self::PAGE_LIMIT
);
} while ($selector->getPaging()->getStartIndex() < $totalNumEntries);
return $customerIds;
}
public static function main()
{
// Generate a refreshable OAuth2 credential for authentication.
$oAuth2Credential = (new OAuth2TokenBuilder())->fromFile()->build();
// See: AdWordsSessionBuilder for setting a client customer ID that is
// different from that specified in your adsapi_php.ini file.
$sessionBuilder = (new AdWordsSessionBuilder())->fromFile()->withOAuth2Credential($oAuth2Credential);
self::runExample(
new AdWordsServices(),
$sessionBuilder,
sys_get_temp_dir()
);
}
}
ParallelReportDownload::main();