{

private const CUSTOMER_ID = 'INSERT_CUSTOMER_ID_HERE';

public static function main()

{

// Either pass the required parameters for this example on the command line, or insert them

// into the constants above.

$options = (new ArgumentParser())->parseCommandArguments([

ArgumentNames::CUSTOMER_ID => GetOpt::REQUIRED_ARGUMENT

]);

// Generate a refreshable OAuth2 credential for authentication.

$oAuth2Credential = (new OAuth2TokenBuilder())->fromFile()->build();

// Construct a Google Ads client configured from a properties file and the

// OAuth2 credentials above.

$googleAdsClient = (new GoogleAdsClientBuilder())->fromFile()

->withOAuth2Credential($oAuth2Credential)

// We set this value to true to show how to use GAPIC v2 source code. You can remove the

// below line if you wish to use the old-style source code. Note that in that case, you

// probably need to modify some parts of the code below to make it work.

// For more information, see

// https://developers.devsite.corp.google.com/google-ads/api/docs/client-libs/php/gapic.

->usingGapicV2Source(true)

->build();

try {

self::runExample(

$googleAdsClient,

$options[ArgumentNames::CUSTOMER_ID] ?: self::CUSTOMER_ID

);

} catch (GoogleAdsException $googleAdsException) {

printf(

"Request with ID '%s' has failed.%sGoogle Ads failure details:%s",

$googleAdsException->getRequestId(),

PHP_EOL,

PHP_EOL

);

foreach ($googleAdsException->getGoogleAdsFailure()->getErrors() as $error) {

/** @var GoogleAdsError $error */

printf(

"\t%s: %s%s",

$error->getErrorCode()->getErrorCode(),

$error->getMessage(),

PHP_EOL

);

}

exit(1);

} catch (ApiException $apiException) {

printf(

"ApiException was thrown with message '%s'.%s",

$apiException->getMessage(),

PHP_EOL

);

exit(1);

}

}

/**

* Runs the example.

*

* @param GoogleAdsClient $googleAdsClient the Google Ads API client

* @param int $customerId the customer ID

*/

// [START generate_historical_metrics]

public static function runExample(

GoogleAdsClient $googleAdsClient,

int $customerId

): void {

$keywordPlanIdeaServiceClient = $googleAdsClient->getKeywordPlanIdeaServiceClient();

// Generates keyword historical metrics based on the specified parameters.

$response = $keywordPlanIdeaServiceClient->generateKeywordHistoricalMetrics(

new GenerateKeywordHistoricalMetricsRequest([

'customer_id' => $customerId,

'keywords' => ['mars cruise', 'cheap cruise', 'jupiter cruise'],

// See https://developers.google.com/google-ads/api/reference/data/geotargets for

// the list of geo target IDs.

// Geo target constant 2840 is for USA.

'geo_target_constants' => [ResourceNames::forGeoTargetConstant(2840)],

'keyword_plan_network' => KeywordPlanNetwork::GOOGLE_SEARCH,

// https://developers.google.com/google-ads/api/reference/data/codes-formats#languages

// for the list of language constant IDs.

// Language constant 1000 is for English.

'language' => ResourceNames::forLanguageConstant(1000)

])

);

// Iterates over the results and print its detail.

foreach ($response->getResults() as $result) {

/** @var GenerateKeywordHistoricalMetricsResult $result */

$metrics = $result->getKeywordMetrics();

printf("The search query: '%s' ", $result->getText());

printf(

"and the following variants: '%s' ",

implode(',', iterator_to_array($result->getCloseVariants()->getIterator()))

);

print "generated the following historical metrics:" . PHP_EOL;

// Approximate number of monthly searches on this query averaged for the past 12 months.

printf(

"Approximate monthly searches: %s%s",

$metrics->hasAvgMonthlySearches()

? sprintf("%d", $metrics->getAvgMonthlySearches())

: "'none'",

PHP_EOL

);

// The competition level for this search query.

printf(

"Competition level: '%s'%s",

KeywordPlanCompetitionLevel::name($metrics->getCompetition()),

PHP_EOL

);

// The competition index for the query in the range [0,100]. This shows how

// competitive ad placement is for a keyword. The level of competition from 0-100 is

// determined by the number of ad slots filled divided by the total number of slots

// available. If not enough data is available, null will be returned.

printf(

"Competition index: %s%s",

$metrics->hasCompetitionIndex()

? sprintf("%d", $metrics->getCompetitionIndex())

: "'none'",

PHP_EOL

);

// Top of page bid low range (20th percentile) in micros for the keyword.

printf(

"Top of page bid low range: %s%s",

$metrics->hasLowTopOfPageBidMicros()

? sprintf("%d", $metrics->getLowTopOfPageBidMicros())

: "'none'",

PHP_EOL

);

// Top of page bid high range (80th percentile) in micros for the keyword.

printf(

"Top of page bid high range: %s%s",

$metrics->hasHighTopOfPageBidMicros()

? sprintf("%d", $metrics->getHighTopOfPageBidMicros())

: "'none'",

PHP_EOL

);

// Approximate number of searches on this query for the past twelve months.

$monthlySearchVolumes =

iterator_to_array($metrics->getMonthlySearchVolumes()->getIterator());

usort(

$monthlySearchVolumes,

// Orders the monthly search volumes by descending year, then descending month.

function (MonthlySearchVolume $volume1, MonthlySearchVolume $volume2) {

$yearsCompared = $volume2->getYear() <=> $volume1->getYear();

if ($yearsCompared != 0) {

return $yearsCompared;

} else {

return $volume2->getMonth() <=> $volume1->getMonth();

}

}

);

// Prints each monthly search volume.

array_walk($monthlySearchVolumes, function (MonthlySearchVolume $monthlySearchVolume) {

printf(

"Approximately %d searches in %s, %s.%s",

$monthlySearchVolume->getMonthlySearches(),

MonthOfYear::name($monthlySearchVolume->getMonth()),

$monthlySearchVolume->getYear(),

PHP_EOL

);

});

print PHP_EOL;

}

}

// [END generate_historical_metrics]