Tạo chỉ số trước đây

Chỉ số trong quá khứ cung cấp các chỉ số (KeywordPlanHistoricalMetrics) về hiệu suất của từ khoá trên Google Tìm kiếm, bao gồm cả các trường sau:

• Số lượt tìm kiếm trung bình hằng tháng (avg_monthly_searches, trung bình trong 12 tháng qua hoặc year_month_range được chỉ định)
• Lượng tìm kiếm hằng tháng gần đúng (monthly_search_volumes, có thể xem dữ liệu trong tối đa 4 năm qua)
• Mức độ cạnh tranh (competition)
• Chỉ số cạnh tranh (competition_index, từ 0 đến 100)
• Phân vị thứ 20 của giá thầu đầu trang (low_top_of_page_bid_micros)
• Phân vị thứ 80 của giá thầu đầu trang (high_top_of_page_bid_micros)
• Chi phí trung bình cho mỗi lượt nhấp (average_cpc_micros, được trả về để hỗ trợ phiên bản cũ khi HistoricalMetricsOptions.include_average_cpc là true)

Nếu bạn đang khám phá các gợi ý từ khoá bằng GenerateKeywordIdeas, thì mỗi GenerateKeywordIdeaResult được trả về đã bao gồm KeywordPlanHistoricalMetrics trong trường keyword_idea_metrics. Gọi GenerateKeywordHistoricalMetrics khi bạn đã có danh sách từ khoá và muốn lọc từ khoá theo lượng tìm kiếm trước đây, mức độ cạnh tranh và giá thầu đầu trang trước khi sắp xếp từ khoá theo chủ đề của nhóm quảng cáo hoặc ước tính hiệu suất bằng chỉ số dự báo.

Tạo chỉ số

Để tạo chỉ số trong quá khứ, hãy gọi KeywordPlanIdeaService.GenerateKeywordHistoricalMetrics với tối đa 10.000 từ khoá cho mỗi yêu cầu và các thông số nhắm mục tiêu mà bạn muốn đưa vào (chẳng hạn như language, tối đa 10 geo_target_constants và keyword_plan_network). Phương thức này sẽ trả về GenerateKeywordHistoricalMetricsResponse chứa danh sách các đối tượng GenerateKeywordHistoricalMetricsResult, mỗi đối tượng có một trường keyword_metrics thuộc loại KeywordPlanHistoricalMetrics. Xin lưu ý rằng API này sẽ loại bỏ các biến thể gần giống nhau (ví dụ: hợp nhất "car" và "cars" thành một kết quả duy nhất và liệt kê các cụm từ tìm kiếm kết hợp trong close_variants), do đó, số lượng kết quả được trả về có thể ít hơn số lượng từ khoá được yêu cầu.

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.V26.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"\tApproximate monthly searches: {metrics.avg_monthly_searches}")

        # The competition level for this search query.
        print(f"\tCompetition 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"\tCompetition index: {metrics.competition_index}")

        # Top of page bid low range (20th percentile) in micros for the keyword.
        print(
            f"\tTop 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(
            "\tTop 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"\tApproximately {month.monthly_searches} searches in "
                f"{month.month.name}, {month.year}"
            )
generate_historical_metrics.py
      

Ruby

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

  # Generates historical metrics and prints the results.
  keyword_plan_idea_service = client.service.keyword_plan_idea

  response = keyword_plan_idea_service.generate_keyword_historical_metrics(
    customer_id: customer_id,
    keywords: ["mars cruise", "cheap cruise", "jupiter cruise"],
    keyword_plan_network: :GOOGLE_SEARCH,

    # For the list of geo target IDs, see:
    # https://developers.google.com/google-ads/api/reference/data/geotargets
    # Geo target constant 2840 is for USA.
    geo_target_constants: [client.path.geo_target_constant("2840")],

    # 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
    language: client.path.language_constant("1000"),
  )

  for result in response.results
    metrics = result.keyword_metrics
    # These metrics include those for both the search query and any variants
    # included in the response.
    puts"The search query '#{result.text}' (and the following variants: " \
        "'#{result.close_variants}'), " \
        "generated the following historical metrics:\n"


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

    # The competition level for this search query.
    puts "\tCompetition 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.
    puts "\tCompetition index: #{metrics.competition_index}"

    # Top of page bid low range (20th percentile) in micros for the keyword.
    puts "\tTop 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.
    puts"\tTop of page bid high range: "
        "#{metrics.high_top_of_page_bid_micros}"

    # Approximate number of searches on this query for the past twelve
    # months.
    for month in metrics.monthly_search_volumes
      puts "\tApproximately #{month.monthly_searches} searches in "
           "#{month.month.name}, #{month.year}"
    end
  end
end
generate_historical_metrics.rb
      

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::V26::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::V26::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
      

curl

Lưu ý: Mặc dù không có mẫu mã REST trực tiếp cho bước này, nhưng bạn có thể thực hiện bằng cách sử dụng yêu cầu REST thủ công.

Tham khảo tài liệu về giao diện REST của Google Ads API và các trang tham khảo theo phương thức cụ thể. Bạn sẽ cần tạo tải trọng JSON dựa trên các định nghĩa proto.

Tài nguyên chính:

• Sử dụng REST
• Cấu trúc giao diện REST
• Ánh xạ trường JSON
• Tham khảo Tài liệu tham khảo API REST để biết dịch vụ và phương thức cụ thể.

Google cập nhật các chỉ số như lượng tìm kiếm hằng tháng dựa trên dữ liệu tìm kiếm của tháng trước.

Ánh xạ tới giao diện người dùng

Bảng sau đây liên kết các tham số KeywordPlanIdeaService.GenerateKeywordHistoricalMetrics với Công cụ lập kế hoạch từ khoá trong giao diện người dùng Google Ads:

Công cụ lập kế hoạch từ khoá trong giao diện người dùng	API Google Ads
Nhập từ khoá	GenerateKeywordHistoricalMetricsRequest.keywords
Vị trí	GenerateKeywordHistoricalMetricsRequest.geo_target_constants
Ngôn ngữ	GenerateKeywordHistoricalMetricsRequest.language
Mạng tìm kiếm	GenerateKeywordHistoricalMetricsRequest.keyword_plan_network
Phạm vi ngày	GenerateKeywordHistoricalMetricsRequest.historical_metrics_options
Giá thầu CPC	HistoricalMetricsOptions.include_average_cpc