הפיקו רעיונות למילות מפתח

באמצעות KeywordPlanIdeaService, תוכלו לקבל הצעות למילות מפתח שרלוונטיות לקמפיין לרשת החיפוש ב-Google, או לאחזר מדדים היסטוריים לרשימה קיימת של מילות מפתח.

יצירת רעיונות

יצירת רעיונות למילות מפתח לקמפיין באמצעות KeywordPlanIdeaService.GenerateKeywordIdeas.

אתם יכולים לספק מילות מפתח וכתובות URL כדי ליצור רעיונות. כדי לצמצם את החיפוש, מגדירים פרמטרים של טירגוט כמו מיקומים, שפה והגדרות רשת. השירות מחזיר נתונים סטטיסטיים היסטוריים, כמו נתונים על נפח החיפושים, כדי לעזור לכם להחליט אם להשתמש במילות המפתח בקמפיין. למשתמשים שמכירים את ממשק המשתמש של Google Ads, זה דומה לכלי לתכנון מילות מפתח.

הערה: לא נדרש משאב KeywordPlan כשקוראים ל-method הזה. אפשר להעביר את הרעיונות למילות מפתח שמתקבלים ישירות אל GenerateAdGroupThemes כדי לארגן אותם לפי נושאים של קבוצות מודעות, להעביר אותם אל GenerateKeywordForecastMetrics (באמצעות CampaignToForecast מוטבע) כדי להעריך את הביצועים העתידיים, או להשתמש בהם כדי ליצור קמפיין להצגת מודעות.

יש כמה דרכים ליצור גרעינים ליצירת רעיונות למילות מפתח:

• כדי לתאר במילים או בביטויים את מה שאתם מפרסמים, השתמשו בKeywordSeed (נדרשת לפחות מילת מפתח אחת ועד 20 מילות מפתח). זה יכול להיות סוג כללי של עסק שאתם מטרגטים, כמו אינסטלטורים, או מוצר או שירות שאתם מציעים, כמו פתיחת סתימות.

• כדי לציין כתובת URL של דף אינטרנט או של אתר שלם שקשורים לעסק, משתמשים בתג UrlSeed. ה-URL הראשוני מטרגט רק כתובת URL ספציפית. אם אין היטים, החיפוש מתרחב באופן אוטומטי לדפים מאותו דומיין.

  כשמזינים כתובות URL, השירות לא משתמש בתוכן של היפר-קישורים כדי ליצור רעיונות למילות מפתח.

• כדי להשתמש גם במילות מפתח וגם בכתובות URL, משתמשים ב-KeywordAndUrlSeed (צריך להזין בין מילת מפתח אחת ל-20 מילות מפתח וכתובת URL).

  אם מציינים גם מילת מפתח בנוסף לכתובת URL, אפשר לקבל כמות גדולה יותר של רעיונות למילות מפתח.KeywordAndUrlSeedUrlSeed

• כדי להגדיר אתר שלם, משתמשים ב-SiteSeed. כשמזינים שם דומיין ברמה עליונה, כמו www.example.com, המערכת יוצרת עד 250,000 רעיונות למילות מפתח על סמך מידע שזמין לכולם.

כדי לצמצם את הטירגוט, אפשר להגדיר language, מיקום (עד 10 geo_target_constants), keyword_plan_network, include_adult_keywords, keyword_annotation (Refine keywords) ו-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	אסימון המשך לדף הבא (לא מופיע בדף האחרון) והמספר הכולל של רעיונות זמינים למילות מפתח.

קוד לדוגמה

Java

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());
    }
  }
}
GenerateKeywordIdeas.java
      

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;
    }
}
GenerateKeywordIdeas.cs
      

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
        );
    }
}
GenerateKeywordIdeas.php
      

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"
        )
generate_keyword_ideas.py
      

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
generate_keyword_ideas.rb
      

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;
}
generate_keyword_ideas.pl
      

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
generate_keyword_ideas.sh
      

מבנה הבקשה והתגובה של 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 Ads:

הכלי לתכנון מילות מפתח בממשק המשתמש	Google Ads API
הזנת מילות מפתח וכתובות URL	GenerateKeywordIdeasRequest.keyword_and_url_seed GenerateKeywordIdeasRequest.keyword_seed GenerateKeywordIdeasRequest.url_seed GenerateKeywordIdeasRequest.site_seed
מיקומים	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