إنشاء أفكار للكلمات الرئيسية

باستخدام KeywordPlanIdeaService، يمكنك الاطّلاع على اقتراحات كلمات رئيسية ذات صلة بحملتك على "شبكة بحث Google"، أو استرداد المقاييس السابقة لقائمة كلمات رئيسية حالية.

إنشاء أفكار

أريد إنشاء أفكار كلمات رئيسية لحملة تتضمّن KeywordPlanIdeaService.GenerateKeywordIdeas.

يمكنك تقديم كلمات رئيسية وعناوين URL أولية لإنشاء أفكار. اضبط معايير الاستهداف، مثل المواقع الجغرافية واللغة وإعدادات الشبكة، لتضييق نطاق البحث. تعرض الخدمة إحصاءات سابقة، مثل بيانات حجم البحث، لمساعدتك في تحديد ما إذا كنت تريد استخدام الكلمات الرئيسية في حملتك. بالنسبة إلى المستخدمين الذين يعرفون واجهة مستخدم "إعلانات Google"، يشبه ذلك أداة تخطيط الكلمات الرئيسية.

تتوفّر عدة طرق يمكنك من خلالها إنشاء كلمات رئيسية أولية لإنشاء أفكار كلمات رئيسية:

  • بالنسبة إلى الكلمات أو العبارات التي تصف ما تعلن عنه، استخدِم KeywordSeed (يتطلّب ذلك كلمة رئيسية واحدة على الأقل وما يصل إلى 20 كلمة رئيسية). يمكن أن يكون هذا النوع العام من الأنشطة التجارية التي تستهدفها، مثل السباكين، أو منتج أو خدمة تقدمها، مثل تنظيف الصرف. يجب أن تلتزم الكلمات الرئيسية الأولية بالقيود العادية لعدد أحرف الكلمات الرئيسية وطولها في "إعلانات Google".

  • لإدخال عنوان URL لصفحة ويب أو موقع إلكتروني كامل مرتبط بنشاطك التجاري، استخدِم UrlSeed. يستهدف عنوان URL الأساسي عنوان URL محددًا فقط. إذا لم تكن هناك نتائج، يتم توسيع نطاق البحث تلقائيًا ليشمل الصفحات من النطاق نفسه.

    بالنسبة إلى عناوين URL الأولية، لا تستخدم الخدمة محتوى الروابط التشعّبية لإنشاء أفكار للكلمات الرئيسية.

  • بالنسبة إلى كلّ من الكلمات الرئيسية الأولية وعناوين URL الأولية، استخدِم KeywordAndUrlSeed (يتطلّب ذلك من كلمة رئيسية واحدة إلى 20 كلمة رئيسية مع عنوان URL).

    يمكن أن يؤدي استخدام KeywordAndUrlSeed إلى الحصول على عدد أكبر من أفكار الكلمات الرئيسية، مقارنةً باستخدام UrlSeed فقط.

  • بالنسبة إلى موقع إلكتروني كامل، استخدِم SiteSeed. عند إدخال اسم نطاق مستوى أعلى، مثل www.example.com، ينشئ الموقع الإلكتروني الأساسي ما يصل إلى 250,000 فكرة للكلمات الرئيسية من المعلومات المتاحة للجميع.

لتضييق نطاق الاستهداف، يمكنك ضبط language والموقع الجغرافي (ما يصل إلى 10 geo_target_constants) وkeyword_plan_network وinclude_adult_keywords وkeyword_annotation (تحسين الكلمات الرئيسية) وhistorical_metrics_options.

يتيح الردّ تقسيم الصفحات (ما يصل إلى 10,000 نتيجة لكل صفحة، ويجب دائمًا التحقّق من 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 مطلوب رقم تعريف العميل المكوّن من 10 أرقام (string) بدون واصلات
seed ‏(oneof) مطلوب حدِّد أحد الخيارات التالية:
• keyword_seed: keywords[] (من سلسلة واحدة إلى 20 سلسلة، راجِع قيود الكلمات الرئيسية).
• ‫url_seed: url (عنوان URL لصفحة معيّنة)
• ‫keyword_and_url_seed: url بالإضافة إلى ما يتراوح بين 1 و20 keywords[].
• site_seed: site (اسم النطاق مثل www.example.com، مع عرض ما يصل إلى 250,000 فكرة).
language اختياري اسم مورد معيار اللغة (languageConstants/{criterion_id}، على سبيل المثال، languageConstants/1000 للغة الإنجليزية). يُرجى الاطّلاع على ثوابت اللغة. في حال حذف هذه المَعلمة، يتم تضمين الكلمات الرئيسية بجميع اللغات.
geo_target_constants[] اختياري ما يصل إلى 10 أسماء لموارد المواقع الجغرافية (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 اختياري (متاح لآخر 4 سنوات، ويتم ضبطه تلقائيًا على آخر 12 شهرًا) و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 (متوسط 12 شهرًا) وmonthly_search_volumes[] (year، month، monthly_searches).
المنافسة: competition (LOW، MEDIUM، HIGH) وcompetition_index (0 إلى 100).
عروض الأسعار وتكلفة النقرة: low_top_of_page_bid_micros (الشريحة المئوية الـ 20) وhigh_top_of_page_bid_micros (الشريحة المئوية الـ 80) و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
      

Perl

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 إلى KeywordPlanIdeaService.GenerateKeywordIdeas باستخدام keywordAndUrlSeed واللغة الإنجليزية (languageConstants/1000) والولايات المتحدة (geoTargetConstants/2840):

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

"أداة تخطيط الكلمات الرئيسية" في واجهة المستخدم Google Ads API
إدخال الكلمات الرئيسية وعناوين URL
المواقع الجغرافية 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