The AdWords API will sunset on April 27, 2022. Migrate to the Google Ads API to take advantage of the latest Google Ads features.

Reporting Samples

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