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();