تولید کردن ایده‌های کلیدواژه

بااستفاده از KeywordPlanIdeaService، می‌توانید پیشنهادهای کلیدواژه مرتبط با پویش «جستجوی Google» خود را کاوش کنید یا سنجه‌های سابقه را برای فهرست کلیدواژه‌های موجود بازیابی کنید.

تولید کردن ایده

ایده‌های کلیدواژه برای پویشی با KeywordPlanIdeaService.GenerateKeywordIdeas تولید کنید.

می‌توانید کلیدواژه و نشانی وب اولیه برای تولید ایده ارائه دهید. پارامترهای هدف‌یابی مانند مکان‌ها، زبان، و تنظیمات شبکه را تنظیم کنید تا جستجویتان را محدود کنید. این سرویس آمار گذشته، مانند داده‌های حجم جستجو را برمی‌گرداند تا به شما کمک کند تصمیم بگیرید که آیا از کلیدواژه‌ها در پویش خود استفاده کنید یا نه. برای کاربرانی که با میانای کاربری Google Ads آشنا هستند، این ابزار شبیه به برنامه‌ریز کلیدواژه است.

چندین روش برای ایجاد کلیدواژه‌های پایه برای تولید ایده‌های کلیدواژه وجود دارد:

  • برای کلمه‌ها یا عبارت‌هایی که آنچه را تبلیغ می‌کنید توصیف می‌کنند، از KeywordSeed استفاده کنید (حداقل ۱ و حداکثر ۲۰ کلیدواژه لازم است). این می‌تواند نوع کلی کسب‌وکاری باشد که هدف‌یابی می‌کنید، مثل لوله‌کش، یا محصول یا خدماتی که ارائه می‌دهید، مثل تمیز کردن لوله فاضلاب. کلیدواژه‌های ابتدایی باید از محدودیت‌های طول و نویسه کلیدواژه Google Ads استاندارد پیروی کنند.

  • برای نشانی وب صفحه وب یا کل وب‌سایت مرتبط با کسب‌وکارتان، از UrlSeed استفاده کنید. نشانی وب اولیه فقط نشانی وب خاصی را هدف قرار می‌دهد. اگر نتیجه‌ای وجود نداشته باشد، جستجو به‌طور خودکار به صفحه‌های همان دامنه گسترش می‌یابد.

    برای نشانی‌های وب اولیه، این سرویس از محتوای اَبَرپیوندها برای تولید ایده‌های کلیدواژه استفاده نمی‌کند.

  • برای هر دو بذر کلیدواژه و بذر نشانی وب، از KeywordAndUrlSeed استفاده کنید (به ۱ تا ۲۰ کلیدواژه به‌همراه نشانی وب نیاز دارد).

    استفاده از KeywordAndUrlSeed می‌تواند درمقایسه با فقط UrlSeed به حجم بیشتری از ایده‌های کلیدواژه منجر شود.

  • برای کل سایت، از SiteSeed استفاده کنید. با ارائه نام دامنه سطح بالا، مثل www.example.com، سایت seed تا ۲۵۰٬۰۰۰ ایده کلیدواژه از اطلاعات دردسترس عموم تولید می‌کند.

برای محدود کردن هدف‌یابی، می‌توانید language، مکان (تا ۱۰ geo_target_constants)، keyword_plan_network، include_adult_keywords، keyword_annotation (پالایش کلیدواژه‌ها)، و historical_metrics_options را پیکربندی کنید.

پاسخ از صفحه‌بندی پشتیبانی می‌کند (تا ۱۰٬۰۰۰ نتیجه در هر صفحه؛ همیشه next_page_token را بررسی کنید تا ببینید آیا صفحه‌های بیشتری دردسترس است یا نه، زیرا ممکن است صفحه‌ای قبل‌از صفحه نهایی کمتر از page_size نتیجه برگرداند). هر GenerateKeywordIdeaResult، text متعارف (با close_variants)، keyword_idea_metrics تاریخی را برای فیلتر کردن قبل‌از تولید سنجه‌های پیش‌بینی، و keyword_annotations اختیاری برمی‌گرداند.

مرجع فیلد درخواست و پاسخ

KeywordPlanIdeaService.GenerateKeywordIdeas را در نقطه پایانی زیر فراخوانی کنید:

POST https://googleads.googleapis.com/v26/customers/{customer_id}:generateKeywordIdeas

جدول زیر فیلدها و محدودیت‌های GenerateKeywordIdeasRequest را خلاصه می‌کند:

فیلد درخواست الزام قالب و محدودیت‌ها
customer_id الزامی شناسه مشتری ۱۰ رقمی (string) بدون خط تیره.
‫seed‏ (oneof) الزامی یکی از این موارد را مشخص کنید:
• keyword_seed: keywords[] (۱ تا ۲۰ رشته؛ محدودیت‌های کلیدواژه را ببینید).
• url_seed: url (نشانی وب صفحه خاص).
• keyword_and_url_seed: url به‌علاوه ۱ تا ۲۰ keywords[].
• site_seed: site (نام دامنه مانند www.example.com، که تا ۲۵۰٬۰۰۰ ایده را برمی‌گرداند).
language اختیاری نام منبع معیار زبان (languageConstants/{criterion_id}، برای مثال، languageConstants/1000 برای انگلیسی). ثابت‌های زبان را ببینید. اگر حذف شود، کلیدواژه‌ها در همه زبان‌ها گنجانده می‌شود.
geo_target_constants[] اختیاری حداکثر ۱۰ نام منبع مکان (geoTargetConstants/{criterion_id}، برای مثال، geoTargetConstants/2840 برای ایالات متحده). هدف‌های جغرافیایی را ببینید. فهرست خالی همه مناطق جغرافیایی را هدف قرار می‌دهد.
keyword_plan_network اختیاری KeywordPlanNetwork (GOOGLE_SEARCH یا GOOGLE_SEARCH_AND_PARTNERS). پیش‌فرض GOOGLE_SEARCH_AND_PARTNERS است.
include_adult_keywords اختیاری bool کنترل می‌کند که آیا کلیدواژه‌های بزرگسالان برگردانده شود یا نه. پیش‌فرض‌ها به false.
keyword_annotation[] اختیاری فهرست مقادیر KeywordPlanKeywordAnnotation (مانند KEYWORD_CONCEPT) برای پر کردن keyword_annotations در هر نتیجه.
aggregate_metrics اختیاری KeywordPlanAggregateMetrics با aggregate_metric_types تنظیم‌شده روی DEVICE برای برگرداندن تعداد جستجوهای بخش‌بندی‌شده براساس دستگاه در aggregate_metric_results.
historical_metrics_options اختیاری HistoricalMetricsOptions که year_month_range اختیاری (دردسترس برای ۴ سال گذشته؛ به‌طور پیش‌فرض ۱۲ ماه گذشته) و include_average_cpc را مشخص می‌کند.
‫page_size و page_token اختیاری حداکثر نتایج در هر صفحه (int32، تا 10,000) و کد ادامه از next_page_token. همه فیلدهای درخواست دیگر را در درخواست‌های صفحه‌بندی‌شده یکسان نگه دارید.

پیام GenerateKeywordIdeaResponse فیلدهای زیر را برمی‌گرداند:

فیلد پاسخ نوع شرح
results[].text string نوشتار ایده کلیدواژه متعارف که نشان‌دهنده پیشنهاد و close_variants[] ترکیبی آن است.
results[].close_variants[] string[] بدیل‌های نزدیک در این GenerateKeywordIdeaResult ترکیب شده‌اند.
results[].keyword_idea_metrics KeywordPlanHistoricalMetrics حجم جستجو: avg_monthly_searches (میانگین ۱۲ ماهه) و monthly_search_volumes[] (year، month، monthly_searches).
رقابت: competition (LOW، MEDIUM، HIGH) و competition_index (0 تا 100).
پیشنهادهای قیمت و CPC: low_top_of_page_bid_micros (صدک بیستم)، high_top_of_page_bid_micros (صدک هشتادم)، و average_cpc_micros (وقتی include_average_cpc = true باشد، پر می‌شود).
results[].keyword_annotations KeywordAnnotations وقتی KEYWORD_CONCEPT در keyword_annotation درخواست شود، پر می‌شود؛ حاوی concepts[] (name، concept_group.name، و concept_group.type) است.
aggregate_metric_results KeywordPlanAggregateMetricResults وقتی DEVICE در aggregate_metrics درخواست شود، پر می‌شود؛ حاوی device_searches[] (MOBILE، TABLET، DESKTOP) است.
‫next_page_token و total_size string، int64 نشان تداوم برای صفحه بعدی (در صفحه آخر حذف شده است) و تعداد کل ایده‌های کلیدواژه دردسترس.

نمونه کد

جاوا

private void runExample(
    GoogleAdsClient googleAdsClient,
    long customerId,
    long languageId,
    List<Long> locationIds,
    List<String> keywords,
    @Nullable String pageUrl) {
  try (KeywordPlanIdeaServiceClient keywordPlanServiceClient =
      googleAdsClient.getLatestVersion().createKeywordPlanIdeaServiceClient()) {
    GenerateKeywordIdeasRequest.Builder requestBuilder =
        GenerateKeywordIdeasRequest.newBuilder()
            .setCustomerId(Long.toString(customerId))
            // Sets the language resource using the provided language ID.
            .setLanguage(ResourceNames.languageConstant(languageId))
            // Sets the network. To restrict to only Google Search, change the parameter below to
            // KeywordPlanNetwork.GOOGLE_SEARCH.
            .setKeywordPlanNetwork(KeywordPlanNetwork.GOOGLE_SEARCH_AND_PARTNERS);

    // Adds the resource name of each location ID to the request.
    for (Long locationId : locationIds) {
      requestBuilder.addGeoTargetConstants(ResourceNames.geoTargetConstant(locationId));
    }

    // Makes sure that keywords and/or page URL were specified. The request must have exactly one
    // of urlSeed, keywordSeed, or keywordAndUrlSeed set.
    if (keywords.isEmpty() && pageUrl == null) {
      throw new IllegalArgumentException(
          "At least one of keywords or page URL is required, but neither was specified.");
    }

    if (keywords.isEmpty()) {
      // Only page URL was specified, so use a UrlSeed.
      requestBuilder.getUrlSeedBuilder().setUrl(pageUrl);
    } else if (pageUrl == null) {
      // Only keywords were specified, so use a KeywordSeed.
      requestBuilder.getKeywordSeedBuilder().addAllKeywords(keywords);
    } else {
      // Both page URL and keywords were specified, so use a KeywordAndUrlSeed.
      requestBuilder.getKeywordAndUrlSeedBuilder().setUrl(pageUrl).addAllKeywords(keywords);
    }

    // Sends the keyword ideas request.
    GenerateKeywordIdeasPagedResponse response =
        keywordPlanServiceClient.generateKeywordIdeas(requestBuilder.build());
    // Prints each result in the response.
    for (GenerateKeywordIdeaResult result : response.iterateAll()) {
      System.out.printf(
          "Keyword idea text '%s' has %d average monthly searches and '%s' competition.%n",
          result.getText(),
          result.getKeywordIdeaMetrics().getAvgMonthlySearches(),
          result.getKeywordIdeaMetrics().getCompetition());
    }
  }
}
      

C#‎

public void Run(GoogleAdsClient client, long customerId, long[] locationIds,
    long languageId, string[] keywordTexts, string pageUrl)
{
    KeywordPlanIdeaServiceClient keywordPlanIdeaService =
        client.GetService(Services.V26.KeywordPlanIdeaService);

    // Make sure that keywords and/or page URL were specified. The request must have
    // exactly one of urlSeed, keywordSeed, or keywordAndUrlSeed set.
    if (keywordTexts.Length == 0 && string.IsNullOrEmpty(pageUrl))
    {
        throw new ArgumentException("At least one of keywords or page URL is required, " +
            "but neither was specified.");
    }

    // Specify the optional arguments of the request as a keywordSeed, UrlSeed,
    // or KeywordAndUrlSeed.
    GenerateKeywordIdeasRequest request = new GenerateKeywordIdeasRequest()
    {
        CustomerId = customerId.ToString(),
    };

    if (keywordTexts.Length == 0)
    {
        // Only page URL was specified, so use a UrlSeed.
        request.UrlSeed = new UrlSeed()
        {
            Url = pageUrl
        };
    }
    else if (string.IsNullOrEmpty(pageUrl))
    {
        // Only keywords were specified, so use a KeywordSeed.
        request.KeywordSeed = new KeywordSeed();
        request.KeywordSeed.Keywords.AddRange(keywordTexts);
    }
    else
    {
        // Both page URL and keywords were specified, so use a KeywordAndUrlSeed.
        request.KeywordAndUrlSeed = new KeywordAndUrlSeed();
        request.KeywordAndUrlSeed.Url = pageUrl;
        request.KeywordAndUrlSeed.Keywords.AddRange(keywordTexts);
    }

    // Create a list of geo target constants based on the resource name of specified
    // location IDs.
    foreach (long locationId in locationIds)
    {
        request.GeoTargetConstants.Add(ResourceNames.GeoTargetConstant(locationId));
    }

    request.Language = ResourceNames.LanguageConstant(languageId);
    // Set the network. To restrict to only Google Search, change the parameter below to
    // KeywordPlanNetwork.GoogleSearch.
    request.KeywordPlanNetwork = KeywordPlanNetwork.GoogleSearchAndPartners;

    try
    {
        // Generate keyword ideas based on the specified parameters.
        var response =
            keywordPlanIdeaService.GenerateKeywordIdeas(request);

        // Iterate over the results and print its detail.
        foreach (GenerateKeywordIdeaResult result in response)
        {
            KeywordPlanHistoricalMetrics metrics = result.KeywordIdeaMetrics;
            Console.WriteLine($"Keyword idea text '{result.Text}' has " +
                $"{metrics.AvgMonthlySearches} average monthly searches and competition " +
                $"is {metrics.Competition}.");
        }
    }
    catch (GoogleAdsException e)
    {
        Console.WriteLine("Failure:");
        Console.WriteLine($"Message: {e.Message}");
        Console.WriteLine($"Failure: {e.Failure}");
        Console.WriteLine($"Request ID: {e.RequestId}");
        throw;
    }
}
      

PHP

public static function runExample(
    GoogleAdsClient $googleAdsClient,
    int $customerId,
    array $locationIds,
    int $languageId,
    array $keywords,
    ?string $pageUrl
) {
    $keywordPlanIdeaServiceClient = $googleAdsClient->getKeywordPlanIdeaServiceClient();

    // Make sure that keywords and/or page URL were specified. The request must have exactly one
    // of urlSeed, keywordSeed, or keywordAndUrlSeed set.
    if (empty($keywords) && is_null($pageUrl)) {
        throw new \InvalidArgumentException(
            'At least one of keywords or page URL is required, but neither was specified.'
        );
    }

    // Specify the optional arguments of the request as a keywordSeed, urlSeed,
    // or keywordAndUrlSeed.
    $requestOptionalArgs = [];
    if (empty($keywords)) {
        // Only page URL was specified, so use a UrlSeed.
        $requestOptionalArgs['url_seed'] = new UrlSeed(['url' => $pageUrl]);
    } elseif (is_null($pageUrl)) {
        // Only keywords were specified, so use a KeywordSeed.
        $requestOptionalArgs['keyword_seed'] = new KeywordSeed(['keywords' => $keywords]);
    } else {
        // Both page URL and keywords were specified, so use a KeywordAndUrlSeed.
        $requestOptionalArgs['keyword_and_url_seed'] =
            new KeywordAndUrlSeed(['url' => $pageUrl, 'keywords' => $keywords]);
    }

    // Create a list of geo target constants based on the resource name of specified location
    // IDs.
    $geoTargetConstants =  array_map(function ($locationId) {
        return ResourceNames::forGeoTargetConstant($locationId);
    }, $locationIds);

    // Generate keyword ideas based on the specified parameters.
    $response = $keywordPlanIdeaServiceClient->generateKeywordIdeas(
        new GenerateKeywordIdeasRequest([
            // Set the language resource using the provided language ID.
            'language' => ResourceNames::forLanguageConstant($languageId),
            'customer_id' => $customerId,
            // Add the resource name of each location ID to the request.
            'geo_target_constants' => $geoTargetConstants,
            // Set the network. To restrict to only Google Search, change the parameter below to
            // KeywordPlanNetwork::GOOGLE_SEARCH.
            'keyword_plan_network' => KeywordPlanNetwork::GOOGLE_SEARCH_AND_PARTNERS
        ] + $requestOptionalArgs)
    );

    // Iterate over the results and print its detail.
    foreach ($response->iterateAllElements() as $result) {
        /** @var GenerateKeywordIdeaResult $result */
        // Note that the competition printed below is enum value.
        // For example, a value of 2 will be returned when the competition is 'LOW'.
        // A mapping of enum names to values can be found at KeywordPlanCompetitionLevel.php.
        printf(
            "Keyword idea text '%s' has %d average monthly searches and competition as %d.%s",
            $result->getText(),
            is_null($result->getKeywordIdeaMetrics()) ?
                0 : $result->getKeywordIdeaMetrics()->getAvgMonthlySearches(),
            is_null($result->getKeywordIdeaMetrics()) ?
                0 : $result->getKeywordIdeaMetrics()->getCompetition(),
            PHP_EOL
        );
    }
}
      

Python

def main(
    client: GoogleAdsClient,
    customer_id: str,
    location_ids: list[str],
    language_id: str,
    keyword_texts: list[str],
    page_url: str,
):
    keyword_plan_idea_service: KeywordPlanIdeaServiceClient = (
        client.get_service("KeywordPlanIdeaService")
    )
    keyword_competition_level_enum: KeywordPlanCompetitionLevelEnum = (
        client.enums.KeywordPlanCompetitionLevelEnum
    )
    keyword_plan_network: KeywordPlanNetworkEnum = (
        client.enums.KeywordPlanNetworkEnum.GOOGLE_SEARCH_AND_PARTNERS
    )
    location_rns: list[str] = map_locations_ids_to_resource_names(
        client, location_ids
    )
    google_ads_service: GoogleAdsServiceClient = client.get_service(
        "GoogleAdsService"
    )
    language_rn: str = google_ads_service.language_constant_path(language_id)

    # Either keywords or a page_url are required to generate keyword ideas
    # so this raises an error if neither are provided.
    if not (keyword_texts or page_url):
        raise ValueError(
            "At least one of keywords or page URL is required, "
            "but neither was specified."
        )

    # Only one of the fields "url_seed", "keyword_seed", or
    # "keyword_and_url_seed" can be set on the request, depending on whether
    # keywords, a page_url or both were passed to this function.
    request: GenerateKeywordIdeasRequest = client.get_type(
        "GenerateKeywordIdeasRequest"
    )
    request.customer_id = customer_id
    request.language = language_rn
    request.geo_target_constants = location_rns
    request.include_adult_keywords = False
    request.keyword_plan_network = keyword_plan_network

    # To generate keyword ideas with only a page_url and no keywords we need
    # to initialize a UrlSeed object with the page_url as the "url" field.
    if not keyword_texts and page_url:
        request.url_seed.url = page_url

    # To generate keyword ideas with only a list of keywords and no page_url
    # we need to initialize a KeywordSeed object and set the "keywords" field
    # to be a list of StringValue objects.
    if keyword_texts and not page_url:
        request.keyword_seed.keywords.extend(keyword_texts)

    # To generate keyword ideas using both a list of keywords and a page_url we
    # need to initialize a KeywordAndUrlSeed object, setting both the "url" and
    # "keywords" fields.
    if keyword_texts and page_url:
        request.keyword_and_url_seed.url = page_url
        request.keyword_and_url_seed.keywords.extend(keyword_texts)

    keyword_ideas = keyword_plan_idea_service.generate_keyword_ideas(
        request=request
    )

    idea: GenerateKeywordIdeaResult
    for idea in keyword_ideas:
        competition_value = idea.keyword_idea_metrics.competition.name
        print(
            f'Keyword idea text "{idea.text}" has '
            f'"{idea.keyword_idea_metrics.avg_monthly_searches}" '
            f'average monthly searches and "{competition_value}" '
            "competition.\n"
        )
      

Ruby

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

  # Make sure that keywords and/or page URL were specified. The request must
  # have exactly one of urlSeed, keywordSeed, or keywordAndUrlSeed set.
  if keywords.reject {|k| k.nil?}.empty? && page_url.nil?
    raise "At least one of keywords or page URL is required."
  end

  kp_idea_service = client.service.keyword_plan_idea

  options_hash = if keywords.empty?
                   seed = client.resource.url_seed do |seed|
                     seed.url = page_url
                   end
                   {url_seed: seed}
                 elsif page_url.nil?
                   seed = client.resource.keyword_seed do |seed|
                     keywords.each do |keyword|
                       seed.keywords << keyword
                     end
                   end
                   {keyword_seed: seed}
                 else
                   seed = client.resource.keyword_and_url_seed do |seed|
                     seed.url = page_url
                     keywords.each do |keyword|
                       seed.keywords << keyword
                     end
                   end
                   {keyword_and_url_seed: seed}
                 end

  geo_target_constants = location_ids.map do |location_id|
    client.path.geo_target_constant(location_id)
  end

  include_adult_keywords = true

  response = kp_idea_service.generate_keyword_ideas(
    customer_id: customer_id,
    language: client.path.language_constant(language_id),
    geo_target_constants: geo_target_constants,
    include_adult_keywords: include_adult_keywords,
    # To restrict to only Google Search, change the parameter below to
    # :GOOGLE_SEARCH
    keyword_plan_network: :GOOGLE_SEARCH_AND_PARTNERS,
    **options_hash
  )

  response.each do |result|
    monthly_searches = if result.keyword_idea_metrics.nil?
                         0
                       else
                         result.keyword_idea_metrics.avg_monthly_searches
                       end
    competition = if result.keyword_idea_metrics.nil?
                    :UNSPECIFIED
                  else
                    result.keyword_idea_metrics.competition
                  end
    puts "Keyword idea text #{result.text} has #{monthly_searches} average " +
        "monthly searches and competition as #{competition}."
  end
end
      

پرل

sub generate_keyword_ideas {
  my (
    $api_client,  $customer_id,   $location_ids,
    $language_id, $keyword_texts, $page_url
  ) = @_;

  # Make sure that keywords and/or page URL were specified. The request must have
  # exactly one of urlSeed, keywordSeed, or keywordAndUrlSeed set.
  if (not scalar @$keyword_texts and not $page_url) {
    die "At least one of keywords or page URL is required, " .
      "but neither was specified.";
  }

  # Specify the optional arguments of the request as a keywordSeed, urlSeed,
  # or keywordAndUrlSeed.
  my $request_option_args = {};
  if (!scalar @$keyword_texts) {
    # Only page URL was specified, so use a UrlSeed.
    $request_option_args->{urlSeed} =
      Google::Ads::GoogleAds::V26::Services::KeywordPlanIdeaService::UrlSeed->
      new({
        url => $page_url
      });
  } elsif (not $page_url) {
    # Only keywords were specified, so use a KeywordSeed.
    $request_option_args->{keywordSeed} =
      Google::Ads::GoogleAds::V26::Services::KeywordPlanIdeaService::KeywordSeed
      ->new({
        keywords => $keyword_texts
      });
  } else {
    # Both page URL and keywords were specified, so use a KeywordAndUrlSeed.
    $request_option_args->{keywordAndUrlSeed} =
      Google::Ads::GoogleAds::V26::Services::KeywordPlanIdeaService::KeywordAndUrlSeed
      ->new({
        url      => $page_url,
        keywords => $keyword_texts
      });
  }

  # Create a list of geo target constants based on the resource name of specified
  # location IDs.
  my $geo_target_constants = [
    map (
      Google::Ads::GoogleAds::V26::Utils::ResourceNames::geo_target_constant(
        $_),
      @$location_ids)];

  # Generate keyword ideas based on the specified parameters.
  my $keyword_ideas_response =
    $api_client->KeywordPlanIdeaService()->generate_keyword_ideas({
      customerId => $customer_id,
      # Set the language resource using the provided language ID.
      language =>
        Google::Ads::GoogleAds::V26::Utils::ResourceNames::language_constant(
        $language_id),
      # Add the resource name of each location ID to the request.
      geoTargetConstants => $geo_target_constants,
      # Set the network. To restrict to only Google Search, change the parameter below
      # to GOOGLE_SEARCH.
      keywordPlanNetwork => GOOGLE_SEARCH_AND_PARTNERS,
      %$request_option_args
    });

  # Iterate over the results and print its detail.
  foreach my $result (@{$keyword_ideas_response->{results}}) {
    printf "Keyword idea text '%s' has %d average monthly searches " .
      "and '%s' competition.\n", $result->{text},
      $result->{keywordIdeaMetrics}{avgMonthlySearches}
      ? $result->{keywordIdeaMetrics}{avgMonthlySearches}
      : 0,
      $result->{keywordIdeaMetrics}{competition}
      ? $result->{keywordIdeaMetrics}{competition}
      : "undef";
  }

  return 1;
}
      

curl

# This code example generates keyword ideas.
#
# Variables:
#   API_VERSION,
#   CUSTOMER_ID,
#   MANAGER_CUSTOMER_ID,
#   OAUTH2_ACCESS_TOKEN:
#     See https://developers.google.com/google-ads/api/rest/auth#request_headers
#     for details.
#
#   LANGUAGE: The resource name of the language to target. This is in the format
#     of "languageConstants/{criterion_id}". See
#     https://developers.google.com/google-ads/api/data/codes-formats#languages
#     for the available criterion_id values.
#   GEO_TARGET_CONSTANT: The resource name of the geo target constant to
#     generate keyword ideas for. This is in the format of
#     "geoTargetConstants/{criterion_id}". See
#     https://developers.google.com/google-ads/api/data/geotargets for the
#     available criterion_id values.
#   KEYWORD: The keyword to generate keyword ideas for.
#   URL: The URL of the website to generate keyword ideas for.
curl -f --request POST \
"https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}:generateKeywordIdeas" \
--header "Content-Type: application/json" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data @- <<EOF
{
  "language": "${LANGUAGE}",
  "geoTargetConstants": [
    "${GEO_TARGET_CONSTANT}"
  ],
  "includeAdultKeywords": false,
  "keywordPlanNetwork": "GOOGLE_SEARCH",
  "keywordAndUrlSeed": {
    "keywords": [
      "${KEYWORD}"
    ],
    "url": "${URL}"
  }
}
EOF
      

ساختار درخواست و پاسخ REST

مثال زیر درخواست POST را بااستفاده از keywordAndUrlSeed، انگلیسی (languageConstants/1000)، و ایالات متحده (geoTargetConstants/2840) به KeywordPlanIdeaService.GenerateKeywordIdeas ارسال می‌کند:

POST https://googleads.googleapis.com/v26/customers/{customer_id}:generateKeywordIdeas
{
  "language": "languageConstants/1000",
  "geoTargetConstants": [
    "geoTargetConstants/2840"
  ],
  "includeAdultKeywords": false,
  "keywordPlanNetwork": "GOOGLE_SEARCH",
  "keywordAnnotation": [
    "KEYWORD_CONCEPT"
  ],
  "keywordAndUrlSeed": {
    "url": "https://www.example.com/mars-cruises",
    "keywords": [
      "mars cruise",
      "space vacation"
    ]
  }
}

پاسخ موفق GenerateKeywordIdeaResult ردیف را در results[] به‌همراه حجم جستجوی گذشته و محدوده‌های پیشنهاد قیمت برمی‌گرداند:

{
  "results": [
    {
      "text": "mars cruise",
      "keywordIdeaMetrics": {
        "avgMonthlySearches": "12100",
        "competition": "MEDIUM",
        "competitionIndex": "54",
        "lowTopOfPageBidMicros": "1450000",
        "highTopOfPageBidMicros": "4800000",
        "monthlySearchVolumes": [
          {
            "year": "2026",
            "month": "MAY",
            "monthlySearches": "14800"
          }
        ]
      },
      "keywordAnnotations": {
        "concepts": [
          {
            "name": "Space Travel",
            "conceptGroup": {
              "name": "Travel",
              "type": "OTHERS"
            }
          }
        ]
      }
    }
  ],
  "totalSize": "1"
}

نگاشت به میانای کاربر

جدول زیر پارامترهای KeywordPlanIdeaService.GenerateKeywordIdeas را به «برنامه‌ریز کلیدواژه» در میانای کاربری Google Ads نگاشت می‌کند:

برنامه‌ریز کلیدواژه در میانای کاربری Google Ads API
کلیدواژه‌ها و نشانی‌های وب را وارد کنید
مکان‌ها GenerateKeywordIdeasRequest.geo_target_constants
کلیدواژه‌های بزرگسالان GenerateKeywordIdeasRequest.include_adult_keywords
زبان GenerateKeywordIdeasRequest.language
شبکه‌های جستجو GenerateKeywordIdeasRequest.keyword_plan_network
پالایش کلیدواژه‌ها GenerateKeywordIdeasRequest.keyword_annotation
محدوده تاریخ GenerateKeywordIdeasRequest.historical_metrics_options
نتایج: کلیدواژه GenerateKeywordIdeaResult.text
نتایج: سنجه‌ها GenerateKeywordIdeaResult.keyword_idea_metrics