สร้างแนวคิดคีย์เวิร์ด

การใช้ KeywordPlanIdeaService ช่วยให้คุณ ค้นพบคำแนะนำคีย์เวิร์ดที่เกี่ยวข้องกับแคมเปญ Google Search หรือดึงข้อมูล เมตริกที่เคยเกิดขึ้น สำหรับรายการคีย์เวิร์ดที่มีอยู่ ได้

สร้างไอเดีย

สร้างไอเดียคีย์เวิร์ดสำหรับแคมเปญด้วย KeywordPlanIdeaService.GenerateKeywordIdeas

คุณสามารถระบุคีย์เวิร์ดและ URL เริ่มต้นเพื่อสร้างไอเดีย ตั้งค่าพารามิเตอร์การกำหนดเป้าหมาย เช่น สถานที่ตั้ง ภาษา และการตั้งค่าเครือข่าย เพื่อจำกัดขอบเขตการค้นหา บริการจะแสดงสถิติที่เคยเกิดขึ้น เช่น ข้อมูลปริมาณการค้นหา เพื่อช่วยคุณตัดสินใจว่าจะใช้คีย์เวิร์ดในแคมเปญหรือไม่ สำหรับผู้ใช้ ที่คุ้นเคยกับ UI ของ Google Ads ฟีเจอร์นี้จะคล้ายกับ เครื่องมือวางแผนคีย์เวิร์ด

หมายเหตุ: ไม่จำเป็นต้องมีทรัพยากร KeywordPlan เมื่อ เรียกใช้เมธอดนี้ คุณสามารถส่งไอเดียคีย์เวิร์ดที่ได้กลับมายัง GenerateAdGroupThemes โดยตรงเพื่อจัดระเบียบไอเดียเหล่านั้นเป็นธีมกลุ่มโฆษณา ส่งไปยัง GenerateKeywordForecastMetrics (โดยใช้ CampaignToForecast แบบอินไลน์) เพื่อประมาณการประสิทธิภาพในอนาคต หรือใช้ไอเดียเหล่านั้นเพื่อสร้างแคมเปญที่แสดงโฆษณา

คุณสามารถสร้างคีย์เวิร์ดเริ่มต้นเพื่อสร้างไอเดียคีย์เวิร์ดได้หลายวิธี ดังนี้

• สำหรับคำหรือวลีที่อธิบายสิ่งที่ต้องการโฆษณา ให้ใช้ KeywordSeed (ต้องมีคีย์เวิร์ดอย่างน้อย 1 รายการและไม่เกิน 20 รายการ) ซึ่งอาจเป็นประเภทธุรกิจทั่วไปที่คุณกำหนดเป้าหมาย เช่น ช่างประปา หรือผลิตภัณฑ์หรือบริการที่คุณนำเสนอ เช่น การล้างท่อระบายน้ำ

• สำหรับ URL ของหน้าเว็บหรือเว็บไซต์ทั้งหมดที่เกี่ยวข้องกับธุรกิจ ให้ใช้ UrlSeed คีย์เวิร์ดเริ่มต้นประเภท URL จะกำหนดเป้าหมายไปยัง URL ที่เฉพาะเจาะจงเท่านั้น หากไม่มีผลลัพธ์ที่ตรงกัน ระบบจะขยายการค้นหาไปยังหน้าเว็บจากโดเมนเดียวกันโดยอัตโนมัติ

  สำหรับคีย์เวิร์ดเริ่มต้นประเภท URL บริการ จะไม่ ใช้เนื้อหาของไฮเปอร์ลิงก์เพื่อสร้างไอเดียคีย์เวิร์ด

• สำหรับทั้งคีย์เวิร์ดเริ่มต้นและ URL เริ่มต้น ให้ใช้ KeywordAndUrlSeed (ต้องมีคีย์เวิร์ด 1 ถึง 20 รายการพร้อมกับ URL)

  การใช้ KeywordAndUrlSeed อาจทำให้เกิดไอเดียคีย์เวิร์ดปริมาณมากกว่าเมื่อเทียบกับการใช้ UrlSeed เพียงอย่างเดียว

• หากต้องการกำหนดเป้าหมายทั้งเว็บไซต์ ให้ใช้ SiteSeed เมื่อระบุชื่อโดเมนระดับบนสุด เช่น www.example.com คีย์เวิร์ดเริ่มต้นประเภทเว็บไซต์จะสร้างไอเดียคีย์เวิร์ดได้สูงสุด 250,000 รายการจากข้อมูลที่เปิดเผยต่อสาธารณะ

หากต้องการจำกัดขอบเขตการกำหนดเป้าหมาย คุณสามารถกำหนดค่า language, location (สูงสุด 10 geo_target_constants), keyword_plan_network, include_adult_keywords, keyword_annotation (ปรับแต่ง คีย์เวิร์ด) และ historical_metrics_options

การตอบกลับรองรับ การแบ่งหน้า (สูงสุด 10,000 ผลลัพธ์ต่อหน้า) โปรดตรวจสอบ next_page_token เสมอเพื่อดูว่ามี หน้าเพิ่มเติมหรือไม่ เนื่องจากหน้าหนึ่งอาจแสดงผลลัพธ์น้อยกว่า page_size ผลลัพธ์ ก่อนหน้าสุดท้าย GenerateKeywordIdeaResult แต่ละรายการจะแสดง text Canonical (พร้อม 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[] (สตริง 1 ถึง 20 รายการ) • url_seed: url (URL ของหน้าเว็บที่เฉพาะเจาะจง) • keyword_and_url_seed: url บวก keywords[] 1 ถึง 20 รายการ • 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	ข้อความไอเดียคีย์เวิร์ด Canonical ที่แสดงคำแนะนำและ 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) ราคาเสนอและ CPC: 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"
}

การแมปกับ UI

ตารางต่อไปนี้จะแมป KeywordPlanIdeaService.GenerateKeywordIdeasพารามิเตอร์กับ เครื่องมือวางแผนคีย์เวิร์ดใน UI ของ Google Ads:

เครื่องมือวางแผนคีย์เวิร์ดใน UI	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
เครือข่าย Search	GenerateKeywordIdeasRequest.keyword_plan_network
ปรับแต่งคีย์เวิร์ด	GenerateKeywordIdeasRequest.keyword_annotation
ช่วงวันที่	GenerateKeywordIdeasRequest.historical_metrics_options
ผลลัพธ์: คีย์เวิร์ด	GenerateKeywordIdeaResult.text
ผลลัพธ์: เมตริก	GenerateKeywordIdeaResult.keyword_idea_metrics