Generate Historical Metrics

Stay organized with collections Save and categorize content based on your preferences.

Java

// Copyright 2022 Google LLC
//
// 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
//
//     https://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.

package com.google.ads.googleads.examples.planning;

import com.beust.jcommander.Parameter;
import com.google.ads.googleads.examples.utils.ArgumentNames;
import com.google.ads.googleads.examples.utils.CodeSampleParams;
import com.google.ads.googleads.lib.GoogleAdsClient;
import com.google.ads.googleads.v12.common.MonthlySearchVolume;
import com.google.ads.googleads.v12.errors.GoogleAdsError;
import com.google.ads.googleads.v12.errors.GoogleAdsException;
import com.google.ads.googleads.v12.services.GenerateHistoricalMetricsResponse;
import com.google.ads.googleads.v12.services.KeywordPlanKeywordHistoricalMetrics;
import com.google.ads.googleads.v12.services.KeywordPlanServiceClient;
import com.google.ads.googleads.v12.utils.ResourceNames;
import com.google.protobuf.ProtocolStringList;
import java.io.FileNotFoundException;
import java.io.IOException;
import java.util.List;

/**
 * Generates historical metrics for a keyword plan. To create a keyword plan, run the {@link
 * AddKeywordPlan} example.
 */
public class GenerateHistoricalMetrics {

  private static class GenerateHistoricalMetricsParams extends CodeSampleParams {

    @Parameter(
        names = ArgumentNames.CUSTOMER_ID,
        description = "The customer in which to create a new keyword plan.")
    public Long customerId;

    @Parameter(
        names = ArgumentNames.KEYWORD_PLAN_ID,
        description = "The keyword plan ID for which to generate metrics.")
    public Long keywordPlanId;
  }

  public static void main(String[] args) {
    GenerateHistoricalMetricsParams params = new GenerateHistoricalMetricsParams();
    if (!params.parseArguments(args)) {

      // Optional, specify the customer ID for which the call is made.
      params.customerId = Long.valueOf("INSERT_CUSTOMER_ID");

      params.keywordPlanId = Long.valueOf("INSERT_KEYWORD_PLAN_ID");
    }
    GoogleAdsClient googleAdsClient = null;
    try {
      googleAdsClient = GoogleAdsClient.newBuilder().fromPropertiesFile().build();
    } catch (FileNotFoundException fnfe) {
      System.err.printf(
          "Failed to load GoogleAdsClient configuration from file. Exception: %s%n", fnfe);
      System.exit(1);
    } catch (IOException ioe) {
      System.err.printf("Failed to create GoogleAdsClient. Exception: %s%n", ioe);
      System.exit(1);
    }

    try {
      new GenerateHistoricalMetrics()
          .runExample(googleAdsClient, params.customerId, params.keywordPlanId);
    } catch (GoogleAdsException gae) {
      // GoogleAdsException is the base class for most exceptions thrown by an API request.
      // Instances of this exception have a message and a GoogleAdsFailure that contains a
      // collection of GoogleAdsErrors that indicate the underlying causes of the
      // GoogleAdsException.
      System.err.printf(
          "Request ID %s failed due to GoogleAdsException. Underlying errors:%n",
          gae.getRequestId());
      int i = 0;
      for (GoogleAdsError googleAdsError : gae.getGoogleAdsFailure().getErrorsList()) {
        System.err.printf("  Error %d: %s%n", i++, googleAdsError);
      }
      System.exit(1);
    }
  }

  /**
   * Runs the code example.
   *
   * @param googleAdsClient the Google Ads API client.
   * @param customerId the client customer ID.
   * @param planId the plan ID.
   */
  private void runExample(GoogleAdsClient googleAdsClient, Long customerId, Long planId) {
    String resourceName = ResourceNames.keywordPlan(customerId, planId);

    try (KeywordPlanServiceClient keywordPlanServiceClient =
        googleAdsClient.getLatestVersion().createKeywordPlanServiceClient()) {
      GenerateHistoricalMetricsResponse response =
          keywordPlanServiceClient.generateHistoricalMetrics(resourceName);

      for (KeywordPlanKeywordHistoricalMetrics metric : response.getMetricsList()) {
        // These metrics include those for both the search query and any close variants included in
        // the response.

        List<String> variants = metric.getCloseVariantsList();
        String variantsList =
            (variants.isEmpty())
                ? ""
                : String.format(" (and the following variants: %s)", String.join(", ", variants));

        System.out.printf(
            "The search query '%s'%s generated the following historical metrics:%n",
            metric.getSearchQuery(), variantsList);

        // Approximate number of monthly searches on this query averaged for the past 12 months.
        System.out.printf(
            "\tApproximate monthly searches: %d.%n",
            metric.getKeywordMetrics().getAvgMonthlySearches());

        // The competition level for this search query.
        System.out.printf(
            "\tCompetition level: %s.%n", metric.getKeywordMetrics().getCompetition().name());

        // 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, None will be returned.
        if (metric.getKeywordMetrics().hasCompetitionIndex()) {
          System.out.printf(
              "\tCompetition index: %d.%n", metric.getKeywordMetrics().getCompetitionIndex());
        }

        // Top of page bid low range (20th percentile) in micros for the keyword.
        if (metric.getKeywordMetrics().hasLowTopOfPageBidMicros()) {
          System.out.printf(
              "\tTop of page bid low range %d.%n",
              metric.getKeywordMetrics().getLowTopOfPageBidMicros());
        }

        // Top of page bid high range (80th percentile) in micros for the keyword.
        if (metric.getKeywordMetrics().hasHighTopOfPageBidMicros()) {
          System.out.printf(
              "\tTop of page bid high range %d.%n",
              metric.getKeywordMetrics().getHighTopOfPageBidMicros());
        }

        // Approximate number of searches on this query for the past twelve months.
        for (MonthlySearchVolume month : metric.getKeywordMetrics().getMonthlySearchVolumesList()) {
          System.out.printf(
              "\tApproximately %d searches in %s, %d.%n",
              month.getMonthlySearches(), month.getMonth().name(), month.getYear());
        }
      }
    }
  }
}

      

C#

// Copyright 2022 Google LLC
//
// 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.

using CommandLine;
using Google.Ads.Gax.Examples;
using Google.Ads.GoogleAds.Lib;
using Google.Ads.GoogleAds.V12.Common;
using Google.Ads.GoogleAds.V12.Errors;
using Google.Ads.GoogleAds.V12.Services;
using System;
using System.Collections.Generic;
using System.Linq;

namespace Google.Ads.GoogleAds.Examples.V12
{
    /// <summary>
    /// This code example generates historical metrics for a keyword plan. To create a keyword
    /// plan, run the AddKeywordPlan example.
    /// </summary>
    public class GenerateHistoricalMetrics : ExampleBase
    {
        /// <summary>
        /// Command line options for running the <see cref="GenerateHistoricalMetrics"/> example.
        /// </summary>
        public class Options : OptionsBase
        {
            /// <summary>
            /// The customer ID for which the call is made.
            /// </summary>
            [Option("customerId", Required = true, HelpText =
                "The customer ID for which the call is made.")]
            public long CustomerId { get; set; }

            /// <summary>
            /// The keyword plan ID.
            /// </summary>
            [Option("keywordPlanId", Required = true, HelpText =
                "The keyword plan ID.")]
            public long KeywordPlanId { get; set; }
        }

        /// <summary>
        /// Main method, to run this code example as a standalone application.
        /// </summary>
        /// <param name="args">The command line arguments.</param>
        public static void Main(string[] args)
        {
            Options options = ExampleUtilities.ParseCommandLine<Options>(args);

            GenerateHistoricalMetrics codeExample = new GenerateHistoricalMetrics();
            Console.WriteLine(codeExample.Description);
            codeExample.Run(new GoogleAdsClient(), options.CustomerId, options.KeywordPlanId);
        }

        /// <summary>
        /// Returns a description about the code example.
        /// </summary>
        public override string Description =>
            "This code example generates historical metrics for a keyword plan. To create a " +
                "keyword plan, run the AddKeywordPlan example.";

        /// <summary>
        /// Runs the code example.
        /// </summary>
        /// <param name="client">The Google Ads client.</param>
        /// <param name="customerId">The customer ID for which the call is made.</param>
        /// <param name="planId">The plan ID.</param>
        public void Run(GoogleAdsClient client, long customerId, long planId)
        {
            KeywordPlanServiceClient keywordPlanIdeaServiceClient =
                client.GetService(Services.V12.KeywordPlanService);

            string resourceName = ResourceNames.KeywordPlan(customerId, planId);

            try
            {
                GenerateHistoricalMetricsResponse response =
                    keywordPlanIdeaServiceClient.GenerateHistoricalMetrics(resourceName);

                foreach (KeywordPlanKeywordHistoricalMetrics metric in response.Metrics)
                {
                    // These metrics include those for both the search query and any close
                    // variants included in the response.

                    List<string> variants = metric.CloseVariants.ToList();
                    string variantsList = (variants.Count == 0) ? "" :
                        $" (and the following variants: {string.Join(", ", variants)})";

                    Console.Write($"The search query '{metric.SearchQuery}'{variantsList} " +
                        $"generated the following historical metrics:");

                    var kwdMetric = metric.KeywordMetrics;

                    // Approximate number of monthly searches on this query averaged for the
                    // past 12 months.
                    Console.WriteLine(
                        $"\tApproximate monthly searches: {kwdMetric.AvgMonthlySearches}.");

                    // The competition level for this search query.
                    Console.WriteLine($"\tCompetition level: {kwdMetric.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, None will
                    // be returned.
                    if (metric.KeywordMetrics.HasCompetitionIndex)
                    {
                        Console.WriteLine($"\tCompetition index: {kwdMetric.CompetitionIndex}.");
                    }

                    // Top of page bid low range (20th percentile) in micros for the keyword.
                    if (kwdMetric.HasLowTopOfPageBidMicros)
                    {
                        Console.WriteLine(
                            $"\tTop of page bid low range {kwdMetric.LowTopOfPageBidMicros}.");
                    }

                    // Top of page bid high range (80th percentile) in micros for the keyword.
                    if (kwdMetric.HasHighTopOfPageBidMicros)
                    {
                        Console.WriteLine(
                            $"\tTop of page bid high range {kwdMetric.HighTopOfPageBidMicros}.");
                    }

                    // Approximate number of searches on this query for the past twelve months.
                    foreach (MonthlySearchVolume month in kwdMetric.MonthlySearchVolumes)
                    {
                        Console.WriteLine($"\tApproximately {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;
            }
        }

    }
}
      

PHP

<?php

/**
 * Copyright 2022 Google LLC
 *
 * 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
 *
 *     https://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\Ads\GoogleAds\Examples\Planning;

require __DIR__ . '/../../vendor/autoload.php';

use GetOpt\GetOpt;
use Google\Ads\GoogleAds\Examples\Utils\ArgumentNames;
use Google\Ads\GoogleAds\Examples\Utils\ArgumentParser;
use Google\Ads\GoogleAds\Lib\OAuth2TokenBuilder;
use Google\Ads\GoogleAds\Lib\V12\GoogleAdsClient;
use Google\Ads\GoogleAds\Lib\V12\GoogleAdsClientBuilder;
use Google\Ads\GoogleAds\Lib\V12\GoogleAdsException;
use Google\Ads\GoogleAds\Util\V12\ResourceNames;
use Google\Ads\GoogleAds\V12\Common\MonthlySearchVolume;
use Google\Ads\GoogleAds\V12\Enums\KeywordPlanCompetitionLevelEnum\KeywordPlanCompetitionLevel;
use Google\Ads\GoogleAds\V12\Enums\MonthOfYearEnum\MonthOfYear;
use Google\Ads\GoogleAds\V12\Errors\GoogleAdsError;
use Google\Ads\GoogleAds\V12\Services\KeywordPlanKeywordHistoricalMetrics;
use Google\ApiCore\ApiException;

/**
 * This example generates historical metrics for a keyword plan. To create a keyword plan,
 * run AddKeywordPlan.php.
 */
class GenerateHistoricalMetrics
{
    private const CUSTOMER_ID = 'INSERT_CUSTOMER_ID_HERE';
    private const KEYWORD_PLAN_ID = 'INSERT_KEYWORD_PLAN_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,
            ArgumentNames::KEYWORD_PLAN_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)
            ->build();

        try {
            self::runExample(
                $googleAdsClient,
                $options[ArgumentNames::CUSTOMER_ID] ?: self::CUSTOMER_ID,
                $options[ArgumentNames::KEYWORD_PLAN_ID] ?: self::KEYWORD_PLAN_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
     * @param int $keywordPlanId the keyword plan ID
     */
    public static function runExample(
        GoogleAdsClient $googleAdsClient,
        int $customerId,
        int $keywordPlanId
    ) {
        $keywordPlanServiceClient = $googleAdsClient->getKeywordPlanServiceClient();

        // Issues a request to generate forecast metrics based on the specific keyword plan ID.
        $generateHistoricalMetricsResponse = $keywordPlanServiceClient->generateHistoricalMetrics(
            ResourceNames::forKeywordPlan($customerId, $keywordPlanId)
        );

        foreach ($generateHistoricalMetricsResponse->getMetrics() as $metric) {
            /** @var KeywordPlanKeywordHistoricalMetrics $metric */
            // These metrics include those for both the search query and any close
            // variants included in the response.
            $variants =
                implode(', ', iterator_to_array($metric->getCloseVariants()->getIterator()));
            printf(
                "The search query, '%s', (and the following variants: %s), generated "
                . "the following historical metrics:%s",
                $metric->getSearchQuery(),
                $variants ? "$variants" : 'None',
                PHP_EOL
            );

            // Approximate number of monthly searches on this query averaged for the past 12 months.
            printf(
                "\tApproximate monthly searches: %d.%s",
                $metric->getKeywordMetrics()->getAvgMonthlySearches(),
                PHP_EOL
            );

            // The competition level for this search query.
            printf(
                "\tCompetition level: '%s'.%s",
                KeywordPlanCompetitionLevel::name($metric->getKeywordMetrics()->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 ad slots available.
            // If not enough data is available, 0 will be returned.
            printf(
                "\tCompetition index: %d.%s",
                $metric->getKeywordMetrics()->getCompetitionIndex(),
                PHP_EOL
            );

            // Top of page bid low range (20th percentile) in micros for the keyword.
            printf(
                "\tTop of page bid low range: %d.%s",
                $metric->getKeywordMetrics()->getLowTopOfPageBidMicros(),
                PHP_EOL
            );

            // Top of page bid high range (80th percentile) in micros for the keyword.
            printf(
                "\tTop of page bid high range: %d.%s",
                $metric->getKeywordMetrics()->getHighTopOfPageBidMicros(),
                PHP_EOL
            );

            // Approximate number of searches on this query for the past twelve months.
            foreach ($metric->getKeywordMetrics()->getMonthlySearchVolumes() as $volume) {
                /** @var MonthlySearchVolume $volume */
                printf(
                    "\tApproximately %d searches in %s, %d.%s",
                    $volume->getMonthlySearches(),
                    MonthOfYear::name($volume->getMonth()),
                    $volume->getYear(),
                    PHP_EOL
                );
            }
        }
    }
}

GenerateHistoricalMetrics::main();

      

Python

#!/usr/bin/env python
# Copyright 2022 Google LLC
#
# 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
#
#     https://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.
"""This example generates historical metrics for a keyword plan.

To create a keyword plan, run the add_keyword_plan.py example.
"""


import argparse
import sys

from google.ads.googleads.client import GoogleAdsClient
from google.ads.googleads.errors import GoogleAdsException


def main(client, customer_id, keyword_plan_id):
    """The main method that creates all necessary entities for the example.

    Args:
        client: an initialized GoogleAdsClient instance.
        customer_id: a client customer ID.
        keyword_plan_id: the ID for a keyword plan.
    """
    keyword_plan_service = client.get_service("KeywordPlanService")
    resource_name = keyword_plan_service.keyword_plan_path(
        customer_id, keyword_plan_id
    )

    response = keyword_plan_service.generate_historical_metrics(
        keyword_plan=resource_name
    )

    for metric in response.metrics:
        # These metrics include those for both the search query and any close
        # variants included in the response.
        print(
            f"The search query, '{metric.search_query}', (and the following "
            f"variants: {', '.join(metric.close_variants)}), generated the "
            "following historical metrics:"
        )

        # Approximate number of monthly searches on this query averaged for
        # the past 12 months.
        print(
            f"\tApproximate monthly searches: {metric.keyword_metrics.avg_monthly_searches}."
        )

        # The competition level for this search query.
        print(
            f"\tCompetition level: {metric.keyword_metrics.competition.name}."
        )

        # 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, None will be returned.
        print(
            f"\tCompetition index: {metric.keyword_metrics.competition_index}."
        )

        # Top of page bid low range (20th percentile) in micros for the keyword.
        print(
            f"\tTop of page bid low range: {metric.keyword_metrics.low_top_of_page_bid_micros}."
        )

        # Top of page bid high range (80th percentile) in micros for the keyword.
        print(
            f"\tTop of page bid high range: {metric.keyword_metrics.high_top_of_page_bid_micros}."
        )

        # Approximate number of searches on this query for the past twelve months.
        for month in metric.keyword_metrics.monthly_search_volumes:
            print(
                f"\tApproximately {month.monthly_searches} searches in {month.month.name}, {month.year}."
            )


if __name__ == "__main__":
    # GoogleAdsClient will read the google-ads.yaml configuration file in the
    # home directory if none is specified.
    googleads_client = GoogleAdsClient.load_from_storage(version="v10")

    parser = argparse.ArgumentParser(
        description="Generates historical metrics for a keyword plan."
    )
    # The following argument(s) should be provided to run the example.
    parser.add_argument(
        "-c",
        "--customer_id",
        type=str,
        required=True,
        help="The Google Ads customer ID.",
    )
    parser.add_argument(
        "-k",
        "--keyword_plan_id",
        type=str,
        required=True,
        help="A Keyword Plan ID.",
    )
    args = parser.parse_args()

    try:
        main(googleads_client, args.customer_id, args.keyword_plan_id)
    except GoogleAdsException as ex:
        print(
            f'Request with ID "{ex.request_id}" failed with status '
            f'"{ex.error.code().name}" and includes the following errors:'
        )
        for error in ex.failure.errors:
            print(f'\tError with message "{error.message}".')
            if error.location:
                for field_path_element in error.location.field_path_elements:
                    print(f"\t\tOn field: {field_path_element.field_name}")
        sys.exit(1)

      

Ruby

#!/usr/bin/env ruby
# Encoding: utf-8
#
# Copyright 2022 Google LLC
#
# 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
#
#     https://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.
#
# This example generates historical metrics for a keyword plan. To create a
# keyword plan, run add_keyword_plan.rb.

require 'optparse'
require 'google/ads/google_ads'

def generate_historical_metrics(customer_id, keyword_plan_id)
  # GoogleAdsClient will read a config file from
  # ENV['HOME']/google_ads_config.rb when called without parameters
  client = Google::Ads::GoogleAds::GoogleAdsClient.new

  kp_service = client.service.keyword_plan
  response = kp_service.generate_historical_metrics(
    keyword_plan: client.path.keyword_plan(customer_id, keyword_plan_id),
  )

  response.metrics.each do |metric|
    puts "The search query '#{metric.search_query}' (and the following " +
      "variants: #{metric.close_variants.join(', ')}) generated the " +
      "following historical metrics:"

    # Approximate number of monthly searches on this query averaged for
    # the past 12 months.
    puts "\tApproximate monthly searches: #{metric.keyword_metrics.avg_monthly_searches}"

    # The competition level for this search query.
    puts "\tCompetition level: #{metric.keyword_metrics.competition.name}"

    # 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, None will be returned.
    puts "\tCompetition index: #{metric.keyword_metrics.competition_index}"

    # Top of page bid low range (20th percentile) in micros for the keyword.
    puts "\tTop of page bid low range: #{metric.keyword_metrics.low_top_of_page_bid_micros}"

    # Top of page bid high range (80th percentile) in micros for the keyword.
    puts "\tTop of page bid high range: #{metric.keyword_metrics.high_top_of_page_bid_micros}"

    # Approximate number of searches on this query for each of the past twelve
    # months.
    metric.keyword_metrics.monthly_search_volumes.each do |month|
      puts "\tApproximately #{month.monthly_searches} searches in #{month.month.name}, #{month.year}"
    end
  end
end

if __FILE__ == $0
  options = {}

  # Running the example with -h will print the command line usage.
  OptionParser.new do |opts|
    opts.banner = sprintf('Usage: %s [options]', File.basename(__FILE__))

    opts.separator ''
    opts.separator 'Options:'

    opts.on('-C', '--customer-id CUSTOMER-ID', String, 'Customer ID') do |v|
      options[:customer_id] = v
    end

    opts.on('-k', '--keyword-plan-id KEYWORD-PLAN-ID', String,
        'Keyword Plan ID') do |v|
      options[:keyword_plan_id] = v
    end

    opts.separator ''
    opts.separator 'Help:'

    opts.on_tail('-h', '--help', 'Show this message') do
      puts opts
      exit
    end
  end.parse!

  begin
    generate_historical_metrics(
      options.fetch(:customer_id).tr("-", ""),
      options.fetch(:keyword_plan_id)
    )
  rescue Google::Ads::GoogleAds::Errors::GoogleAdsError => e
    e.failure.errors.each do |error|
      STDERR.printf("Error with message: %s\n", error.message)
      if error.location
        error.location.field_path_elements.each do |field_path_element|
          STDERR.printf("\tOn field: %s\n", field_path_element.field_name)
        end
      end
      error.error_code.to_h.each do |k, v|
        next if v == :UNSPECIFIED
        STDERR.printf("\tType: %s\n\tCode: %s\n", k, v)
      end
    end
    raise
  end
end

      

Perl

#!/usr/bin/perl -w
#
# Copyright 2022, Google LLC
#
# 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.
#
# This example generates historical metrics for a keyword plan. To create a
# keyword plan, run add_keyword_plan.pl.

use strict;
use warnings;
use utf8;

use FindBin qw($Bin);
use lib "$Bin/../../lib";
use Google::Ads::GoogleAds::Client;
use Google::Ads::GoogleAds::Utils::GoogleAdsHelper;
use Google::Ads::GoogleAds::V12::Utils::ResourceNames;

use Getopt::Long qw(:config auto_help);
use Pod::Usage;
use Cwd qw(abs_path);

sub generate_historical_metrics {
  my ($api_client, $customer_id, $keyword_plan_id) = @_;

  my $historical_metrics_response =
    $api_client->KeywordPlanService()->generate_historical_metrics({
      keywordPlan =>
        Google::Ads::GoogleAds::V12::Utils::ResourceNames::keyword_plan(
        $customer_id, $keyword_plan_id
        )});

  foreach my $metric (@{$historical_metrics_response->{metrics}}) {
    # 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",
      $metric->{searchQuery},
      $metric->{closeVariants}
      ? join(', ', $metric->{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->{keywordMetrics}{avgMonthlySearches});

    # The competition level for this search query.
    printf "\tCompetition level: %s.\n",
      value_or_undef($metric->{keywordMetrics}{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->{keywordMetrics}{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->{keywordMetrics}{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->{keywordMetrics}{highTopOfPageBidMicros});

    # Approximate number of searches on this query for the past twelve months.
    foreach my $month (@{$metric->{keywordMetrics}{monthlySearchVolumes}}) {
      printf "\tApproximately %d searches in %s, %s.\n",
        $month->{monthlySearches}, $month->{month}, $month->{year};
    }
  }

  return 1;
}

# Returns the input value as a string if it's defined, otherwise returns "(undef)".
sub value_or_undef {
  my ($value) = @_;
  return $value ? "$value" : "(undef)";
}

# Don't run the example if the file is being included.
if (abs_path($0) ne abs_path(__FILE__)) {
  return 1;
}

# Get Google Ads Client, credentials will be read from ~/googleads.properties.
my $api_client = Google::Ads::GoogleAds::Client->new();

# By default examples are set to die on any server returned fault.
$api_client->set_die_on_faults(1);

my $customer_id     = undef;
my $keyword_plan_id = undef;

# Parameters passed on the command line will override any parameters set in code.
GetOptions(
  "customer_id=s"     => \$customer_id,
  "keyword_plan_id=i" => \$keyword_plan_id
);

# Print the help message if the parameters are not initialized in the code nor
# in the command line.
pod2usage(2) if not check_params($customer_id, $keyword_plan_id);

# Call the example.
generate_historical_metrics($api_client, $customer_id =~ s/-//gr,
  $keyword_plan_id);

=pod

=head1 NAME

generate_historical_metrics

=head1 DESCRIPTION

This example generates historical metrics for a keyword plan. To create a keyword plan,
run add_keyword_plan.pl

=head1 SYNOPSIS

generate_historical_metrics.pl [options]

    -help                       Show the help message.
    -customer_id                The Google Ads customer ID.
    -keyword_plan_id            The keyword plan ID.

=cut