Generate Historical Metrics

    • Historical metrics provide data on past keyword performance on Google Search, including search volume, competition level, and bid ranges.

    • These metrics can be used to narrow down a large list of keywords based on their performance.

    • To obtain historical metrics, you can use the GenerateKeywordHistoricalMetrics method with specified parameters like keywords, geo targets, and language.

    • The functionality of generating historical metrics is similar to the Keyword Planner tool in the Google Ads UI.

    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 
 . 
 V22 
 . 
 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::V22::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::V22::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: