Generate Historical Metrics

    Historical metrics provide metrics on how keywords have previously performed on Google Search including:

    • Average monthly searches (past 12 months)
    • Approximate monthly search volume (per month)
    • Competition level
    • Competition index
    • 20th percentile of bids
    • 80th percentile of bids

    You can use historical metrics to reduce a large set of keywords to a more manageable size based on the performance. If you already know the keywords you want to use, you can skip historical metrics and go straight to forecast metrics .

    Generate metrics

    To generate historical metrics call KeywordPlanIdeaService.GenerateKeywordHistoricalMetrics with the parameters you would like to include.

    Java

     private 
  
 void 
  
 runExample 
 ( 
 GoogleAdsClient 
  
 googleAdsClient 
 , 
  
 Long 
  
 customerId 
 ) 
  
 { 
  
 GenerateKeywordHistoricalMetricsRequest 
  
 request 
  
 = 
  
 GenerateKeywordHistoricalMetricsRequest 
 . 
 newBuilder 
 () 
  
 . 
 setCustomerId 
 ( 
 String 
 . 
 valueOf 
 ( 
 customerId 
 )) 
  
 . 
 addAllKeywords 
 ( 
 Arrays 
 . 
 asList 
 ( 
 "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. 
  
 . 
 addGeoTargetConstants 
 ( 
 ResourceNames 
 . 
 geoTargetConstant 
 ( 
 2840 
 )) 
  
 . 
 setKeywordPlanNetwork 
 ( 
 KeywordPlanNetwork 
 . 
 GOOGLE_SEARCH 
 ) 
  
 // See 
  
 // 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. 
  
 . 
 setLanguage 
 ( 
 ResourceNames 
 . 
 languageConstant 
 ( 
 1000 
 )) 
  
 . 
 build 
 (); 
  
 try 
  
 ( 
 KeywordPlanIdeaServiceClient 
  
 keywordPlanIdeaServiceClient 
  
 = 
  
 googleAdsClient 
 . 
 getLatestVersion 
 (). 
 createKeywordPlanIdeaServiceClient 
 ()) 
  
 { 
  
 GenerateKeywordHistoricalMetricsResponse 
  
 response 
  
 = 
  
 keywordPlanIdeaServiceClient 
 . 
 generateKeywordHistoricalMetrics 
 ( 
 request 
 ); 
  
 for 
  
 ( 
 GenerateKeywordHistoricalMetricsResult 
  
 result 
  
 : 
  
 response 
 . 
 getResultsList 
 ()) 
  
 { 
  
 KeywordPlanHistoricalMetrics 
  
 metrics 
  
 = 
  
 result 
 . 
 getKeywordMetrics 
 (); 
  
 System 
 . 
 out 
 . 
 printf 
 ( 
 "The search query: %s%n" 
 , 
  
 result 
 . 
 getText 
 ()); 
  
 System 
 . 
 out 
 . 
 printf 
 ( 
  
 "and the following variants: %s%n" 
 , 
  
 Joiner 
 . 
 on 
 ( 
 "," 
 ). 
 join 
 ( 
 result 
 . 
 getCloseVariantsList 
 ())); 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 "generated the following historical metrics:" 
 ); 
  
 // Approximate number of monthly searches on this query averaged for the past 12 
  
 // months. 
  
 System 
 . 
 out 
 . 
 printf 
 ( 
  
 "Approximate monthly searches: %s%n" 
 , 
  
 metrics 
 . 
 hasAvgMonthlySearches 
 () 
  
 ? 
  
 metrics 
 . 
 getAvgMonthlySearches 
 () 
  
 : 
  
 null 
 ); 
  
 // The competition level for this search query. 
  
 System 
 . 
 out 
 . 
 printf 
 ( 
 "Competition level: %s%n" 
 , 
  
 metrics 
 . 
 getCompetition 
 ()); 
  
 // 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. 
  
 System 
 . 
 out 
 . 
 printf 
 ( 
  
 "Competition index: %s%n" 
 , 
  
 metrics 
 . 
 hasCompetitionIndex 
 () 
  
 ? 
  
 metrics 
 . 
 getCompetitionIndex 
 () 
  
 : 
  
 null 
 ); 
  
 // Top of page bid low range (20th percentile) in micros for the keyword. 
  
 System 
 . 
 out 
 . 
 printf 
 ( 
  
 "Top of page bid low range: %s%n" 
 , 
  
 metrics 
 . 
 hasLowTopOfPageBidMicros 
 () 
  
 ? 
  
 metrics 
 . 
 getLowTopOfPageBidMicros 
 () 
  
 : 
  
 null 
 ); 
  
 // Top of page bid high range (80th percentile) in micros for the keyword. 
  
 System 
 . 
 out 
 . 
 printf 
 ( 
  
 "Top of page bid high range: %s%n" 
 , 
  
 metrics 
 . 
 hasHighTopOfPageBidMicros 
 () 
  
 ? 
  
 metrics 
 . 
 getHighTopOfPageBidMicros 
 () 
  
 : 
  
 null 
 ); 
  
 // Approximate number of searches on this query for the past twelve months. 
  
 metrics 
 . 
 getMonthlySearchVolumesList 
 (). 
 stream 
 () 
  
 // Orders the monthly search volumes by descending year, then descending month. 
  
 . 
 sorted 
 ( 
  
 ( 
 a 
 , 
  
 b 
 ) 
  
 - 
>  
 ComparisonChain 
 . 
 start 
 () 
  
 . 
 compare 
 ( 
 b 
 . 
 getYear 
 (), 
  
 a 
 . 
 getYear 
 ()) 
  
 . 
 compare 
 ( 
 b 
 . 
 getMonth 
 (), 
  
 a 
 . 
 getMonth 
 ()) 
  
 . 
 result 
 ()) 
  
 // Prints each monthly search volume. 
  
 . 
 forEachOrdered 
 ( 
  
 monthlySearchVolume 
  
 - 
>  
 System 
 . 
 out 
 . 
 printf 
 ( 
  
 "Approximately %d searches in %s, %s%n" 
 , 
  
 monthlySearchVolume 
 . 
 getMonthlySearches 
 (), 
  
 monthlySearchVolume 
 . 
 getMonth 
 (), 
  
 monthlySearchVolume 
 . 
 getYear 
 ())); 
  
 } 
  
 } 
 } 
 
      GenerateHistoricalMetrics 
 . 
 java

    C#

     public 
  
 void 
  
 Run 
 ( 
 GoogleAdsClient 
  
 client 
 , 
  
 long 
  
 customerId 
 ) 
 { 
  
 KeywordPlanIdeaServiceClient 
  
 keywordPlanIdeaService 
  
 = 
  
 client 
 . 
 GetService 
 ( 
 Services 
 . 
 V21 
 . 
 KeywordPlanIdeaService 
 ); 
  
 GenerateKeywordHistoricalMetricsRequest 
  
 request 
  
 = 
  
 new 
  
 GenerateKeywordHistoricalMetricsRequest 
 () 
  
 { 
  
 CustomerId 
  
 = 
  
 customerId 
 . 
 ToString 
 (), 
  
 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. 
  
 GeoTargetConstants 
  
 = 
  
 { 
  
 ResourceNames 
 . 
 GeoTargetConstant 
 ( 
 2840 
 ) 
  
 }, 
  
 KeywordPlanNetwork 
  
 = 
  
 KeywordPlanNetwork 
 . 
 GoogleSearch 
 , 
  
 // See  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 
 . 
 LanguageConstant 
 ( 
 1000 
 ) 
  
 }; 
  
 try 
  
 { 
  
 GenerateKeywordHistoricalMetricsResponse 
  
 response 
  
 = 
  
 keywordPlanIdeaService 
 . 
 GenerateKeywordHistoricalMetrics 
 ( 
 request 
 ); 
  
 foreach 
  
 ( 
 GenerateKeywordHistoricalMetricsResult 
  
 result 
  
 in 
  
 response 
 . 
 Results 
 ) 
  
 { 
  
 KeywordPlanHistoricalMetrics 
  
 metrics 
  
 = 
  
 result 
 . 
 KeywordMetrics 
 ; 
  
 Console 
 . 
 WriteLine 
 ( 
 $"The search query {result.Text}" 
 ); 
  
 Console 
 . 
 WriteLine 
 ( 
 "and the following variants: " 
  
 + 
  
 $"{String.Join(" 
 , 
 ", result.CloseVariants)}" 
 ); 
  
 Console 
 . 
 WriteLine 
 ( 
 "Generated the following historical metrics:" 
 ); 
  
 // Approximate number of monthly searches on this query averaged for the past 12 
  
 // months. 
  
 Console 
 . 
 WriteLine 
 ( 
 $"Approximate monthly searches: {metrics.AvgMonthlySearches}" 
 ); 
  
 // The competition level for this search query. 
  
 Console 
 . 
 WriteLine 
 ( 
 $"Competition level: {metrics.Competition}" 
 ); 
  
 // 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. 
  
 Console 
 . 
 WriteLine 
 ( 
 $"Competition index: {metrics.CompetitionIndex}" 
 ); 
  
 // Top of page bid low range (20th percentile) in micros for the keyword. 
  
 Console 
 . 
 WriteLine 
 ( 
 $"Top of page bid low range: {metrics.LowTopOfPageBidMicros}" 
 ); 
  
 // Top of page bid high range (80th percentile) in micros for the keyword. 
  
 Console 
 . 
 WriteLine 
 ( 
 $"Top of page bid high range: {metrics.HighTopOfPageBidMicros}" 
 ); 
  
 // Approximate number of searches on this query for the past twelve months. 
  
 foreach 
  
 ( 
 MonthlySearchVolume 
  
 month 
  
 in 
  
 metrics 
 . 
 MonthlySearchVolumes 
 ) 
  
 { 
  
 Console 
 . 
 WriteLine 
 ( 
 $"Approximately {month.MonthlySearches} searches in " 
  
 + 
  
 $"{month.Month}, {month.Year}" 
 ); 
  
 } 
  
 } 
  
 } 
  
 catch 
  
 ( 
 GoogleAdsException 
  
 e 
 ) 
  
 { 
  
 Console 
 . 
 WriteLine 
 ( 
 "Failure:" 
 ); 
  
 Console 
 . 
 WriteLine 
 ( 
 $"Message: {e.Message}" 
 ); 
  
 Console 
 . 
 WriteLine 
 ( 
 $"Failure: {e.Failure}" 
 ); 
  
 Console 
 . 
 WriteLine 
 ( 
 $"Request ID: {e.RequestId}" 
 ); 
  
 throw 
 ; 
  
 } 
 } 
 
      GenerateHistoricalMetrics 
 . 
 cs

    PHP

     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; 
 } 
 } 
     GenerateHistoricalMetrics.php

    Python

     def 
  
 main 
 ( 
 client 
 : 
 GoogleAdsClient 
 , 
 customer_id 
 : 
 str 
 ): 
  
 """The main method that creates all necessary entities for the example. 
 Args: 
 client: an initialized GoogleAdsClient instance. 
 customer_id: a client customer ID. 
 """ 
 generate_historical_metrics 
 ( 
 client 
 , 
 customer_id 
 ) 
 def 
  
 generate_historical_metrics 
 ( 
 client 
 : 
 GoogleAdsClient 
 , 
 customer_id 
 : 
 str 
 ): 
  
 """Generates historical metrics and prints the results. 
 Args: 
 client: an initialized GoogleAdsClient instance. 
 customer_id: a client customer ID. 
 """ 
 googleads_service 
 : 
 GoogleAdsServiceClient 
 = 
 client 
 . 
 get_service 
 ( 
 "GoogleAdsService" 
 ) 
 keyword_plan_idea_service 
 : 
 KeywordPlanIdeaServiceClient 
 = 
 ( 
 client 
 . 
 get_service 
 ( 
 "KeywordPlanIdeaService" 
 ) 
 ) 
 request 
 : 
 GenerateKeywordHistoricalMetricsRequest 
 = 
 client 
 . 
 get_type 
 ( 
 "GenerateKeywordHistoricalMetricsRequest" 
 ) 
 request 
 . 
 customer_id 
 = 
 customer_id 
 request 
 . 
 keywords 
 = 
 [ 
 "mars cruise" 
 , 
 "cheap cruise" 
 , 
 "jupiter cruise" 
 ] 
 # Geo target constant 2840 is for USA. 
 request 
 . 
 geo_target_constants 
 . 
 append 
 ( 
 googleads_service 
 . 
 geo_target_constant_path 
 ( 
 "2840" 
 ) 
 ) 
 request 
 . 
 keyword_plan_network 
 = 
 ( 
 client 
 . 
 enums 
 . 
 KeywordPlanNetworkEnum 
 . 
 GOOGLE_SEARCH 
 ) 
 # Language criteria 1000 is for English. For the list of language criteria 
 # IDs, see: 
 # https://developers.google.com/google-ads/api/reference/data/codes-formats#languages 
 request 
 . 
 language 
 = 
 googleads_service 
 . 
 language_constant_path 
 ( 
 "1000" 
 ) 
 response 
 : 
 GenerateKeywordHistoricalMetricsResponse 
 = 
 ( 
 keyword_plan_idea_service 
 . 
 generate_keyword_historical_metrics 
 ( 
 request 
 = 
 request 
 ) 
 ) 
 results 
 : 
 Iterable 
 [ 
 GenerateKeywordHistoricalMetricsResult 
 ] 
 = 
 response 
 . 
 results 
 for 
 result 
 in 
 results 
 : 
 metrics 
 : 
 KeywordPlanHistoricalMetrics 
 = 
 result 
 . 
 keyword_metrics 
 # These metrics include those for both the search query and any variants 
 # included in the response. 
 print 
 ( 
 f 
 "The search query ' 
 { 
 result 
 . 
 text 
 } 
 ' (and the following variants: " 
 f 
 "' 
 { 
 result 
 . 
 close_variants 
  
 if 
  
 result 
 . 
 close_variants 
  
 else 
  
 'None' 
 } 
 '), " 
 "generated the following historical metrics: 
 \n 
 " 
 ) 
 # Approximate number of monthly searches on this query averaged for the 
 # past 12 months. 
 print 
 ( 
 f 
 " 
 \t 
 Approximate monthly searches: 
 { 
 metrics 
 . 
 avg_monthly_searches 
 } 
 " 
 ) 
 # The competition level for this search query. 
 print 
 ( 
 f 
 " 
 \t 
 Competition level: 
 { 
 metrics 
 . 
 competition 
 } 
 " 
 ) 
 # 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 ad slots available. If not enough data 
 # is available, undef will be returned. 
 print 
 ( 
 f 
 " 
 \t 
 Competition index: 
 { 
 metrics 
 . 
 competition_index 
 } 
 " 
 ) 
 # Top of page bid low range (20th percentile) in micros for the keyword. 
 print 
 ( 
 f 
 " 
 \t 
 Top of page bid low range: 
 { 
 metrics 
 . 
 low_top_of_page_bid_micros 
 } 
 " 
 ) 
 # Top of page bid high range (80th percentile) in micros for the 
 # keyword. 
 print 
 ( 
 " 
 \t 
 Top of page bid high range: " 
 f 
 " 
 { 
 metrics 
 . 
 high_top_of_page_bid_micros 
 } 
 " 
 ) 
 # Approximate number of searches on this query for the past twelve 
 # months. 
 months 
 : 
 Iterable 
 [ 
 MonthlySearchVolume 
 ] 
 = 
 metrics 
 . 
 monthly_search_volumes 
 for 
 month 
 in 
 months 
 : 
 print 
 ( 
 f 
 " 
 \t 
 Approximately 
 { 
 month 
 . 
 monthly_searches 
 } 
 searches in " 
 f 
 " 
 { 
 month 
 . 
 month 
 . 
 name 
 } 
 , 
 { 
 month 
 . 
 year 
 } 
 " 
 ) 
 
      generate_historical_metrics 
 . 
 py

    Ruby

    This example is not yet available in Ruby; you can take a look at the other languages.

    Perl

     sub 
  
 generate_historical_metrics 
  
 { 
  
 my 
  
 ( 
 $api_client 
 , 
  
 $customer_id 
 ) 
  
 = 
  
 @_ 
 ; 
  
 my 
  
 $keyword_historical_metrics_response 
  
 = 
  
 $api_client 
 - 
> KeywordPlanIdeaService 
 () 
 - 
> generate_keyword_historical_metrics 
 ({ 
  
 customerId 
  
 = 
>  
 $customer_id 
 , 
  
 keywords 
  
 = 
>  
 [ 
 "mars cruise" 
 , 
  
 "cheap cruise" 
 , 
  
 "jupiter cruise" 
 ], 
  
 # Geo target constant 2840 is for USA. 
  
 geoTargetConstants 
  
 = 
>  
 [ 
  
 Google::Ads::GoogleAds::V21::Utils::ResourceNames:: 
 geo_target_constant 
 ( 
  
 2840 
 ) 
  
 ], 
  
 keywordPlanNetwork 
  
 = 
>  
 'GOOGLE_SEARCH' 
 , 
  
 # Language criteria 1000 is for English. See 
  
 # https://developers.google.com/google-ads/api/reference/data/codes-formats#languages 
  
 # for the list of language criteria IDs. 
  
 language 
  
 = 
>  
 Google::Ads::GoogleAds::V21::Utils::ResourceNames:: 
 language_constant 
 ( 
  
 1000 
 )}); 
  
 foreach 
  
 my 
  
 $result 
  
 ( 
 @ 
 { 
 $keyword_historical_metrics_response 
 - 
> { 
 results 
 }}) 
  
 { 
  
 my 
  
 $metric 
  
 = 
  
 $result 
 - 
> { 
 keywordMetrics 
 }; 
  
 # These metrics include those for both the search query and any 
  
 # variants included in the response. 
  
 # If the metric is undefined, print (undef) as a placeholder. 
  
 printf 
 "The search query, %s, (and the following variants: %s), generated the following historical metrics:\n" 
 , 
  
 $result 
 - 
> { 
 text 
 }, 
  
 $result 
 - 
> { 
 closeVariants 
 } 
  
 ? 
  
 join 
 ( 
 ', ' 
 , 
  
 $result 
 - 
> { 
 closeVariants 
 }) 
  
 : 
  
 "(undef)" 
 ; 
  
 # Approximate number of monthly searches on this query averaged for 
  
 # the past 12 months. 
  
 printf 
  
 "\tApproximate monthly searches: %s.\n" 
 , 
  
 value_or_undef 
 ( 
 $metric 
 - 
> { 
 avgMonthlySearches 
 }); 
  
 # The competition level for this search query. 
  
 printf 
  
 "\tCompetition level: %s.\n" 
 , 
  
 value_or_undef 
 ( 
 $metric 
 - 
> { 
 competition 
 }); 
  
 # 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 ad slots available. If not enough data is available, undef will 
  
 # be returned. 
  
 printf 
  
 "\tCompetition index: %s.\n" 
 , 
  
 value_or_undef 
 ( 
 $metric 
 - 
> { 
 competitionIndex 
 }); 
  
 # Top of page bid low range (20th percentile) in micros for the keyword. 
  
 printf 
  
 "\tTop of page bid low range: %s.\n" 
 , 
  
 value_or_undef 
 ( 
 $metric 
 - 
> { 
 lowTopOfPageBidMicros 
 }); 
  
 # Top of page bid high range (80th percentile) in micros for the keyword. 
  
 printf 
  
 "\tTop of page bid high range: %s.\n" 
 , 
  
 value_or_undef 
 ( 
 $metric 
 - 
> { 
 highTopOfPageBidMicros 
 }); 
  
 # Approximate number of searches on this query for the past twelve months. 
  
 foreach 
  
 my 
  
 $month 
  
 ( 
 @ 
 { 
 $metric 
 - 
> { 
 monthlySearchVolumes 
 }}) 
  
 { 
  
 printf 
  
 "\tApproximately %d searches in %s, %s.\n" 
 , 
  
 $month 
 - 
> { 
 monthlySearches 
 }, 
  
 $month 
 - 
> { 
 month 
 }, 
  
 $month 
 - 
> { 
 year 
 }; 
  
 } 
  
 } 
  
 return 
  
 1 
 ; 
 } 
 
      generate_historical_metrics 
 . 
 pl

    Metrics like search volume are updated monthly by looking at the last month's search volume. This is the same data as Google Trends .

    Map to the UI

    KeywordPlanIdeaService.GenerateKeywordHistoricalMetrics has similar functionality in the UI's Keyword Planner.

    Keyword Planner UI Google Ads API
    Enter Keywords GenerateKeywordHistoricalMetricsRequest.keywords
    Locations GenerateKeywordHistoricalMetricsRequest.geo_target_constants
    Language GenerateKeywordHistoricalMetricsRequest.language
    Search Networks GenerateKeywordHistoricalMetricsRequest.keyword_plan_network
    Date Range GenerateKeywordHistoricalMetricsRequest.historical_metrics_options
    CPC Bid HistoricalMetricsOptions.include_average_cpc
    Previous
    Generate ad group themes
    Next
    Generate forecast metrics
    Create a Mobile Website
    View Site in Mobile | Classic
    Share by: