您可以使用 KeywordPlanIdeaService，找出與 Google 搜尋廣告活動相關的關鍵字建議，或擷取現有關鍵字清單的歷來指標。
發想創意
使用 KeywordPlanIdeaService.GenerateKeywordIdeas 為廣告活動生成關鍵字提案。
您可以提供關鍵字和網址種子來產生提案。設定指定目標參數 (例如地區、語言和聯播網設定)，縮小搜尋範圍。這項服務會傳回歷來統計資料 (例如搜尋量資料)，協助您決定是否要在廣告活動中使用這些關鍵字。如果您熟悉 Google Ads 使用者介面，這項功能與關鍵字規劃工具類似。
您可以透過下列幾種方式建立種子，產生關鍵字提案：
如要使用字詞或詞組描述廣告宣傳內容，請使用
KeywordSeed(至少須提供 1 個關鍵字，最多 20 個)。這可以是您指定的商家類型 (例如水電工)，或是您提供的產品或服務 (例如排水管清潔)。如要提供與商家相關的網頁或整個網站的網址，請使用
UrlSeed。網址種子只會指定特定網址。如果沒有任何結果，搜尋範圍會自動擴大至相同網域的網頁。如果是網址種子，這項服務不會使用超連結內容產生關鍵字提案。
不論是關鍵字種子還是網址種子，請使用
KeywordAndUrlSeed(需要 1 到 20 個關鍵字和一個網址)。相較於只使用
UrlSeed，使用KeywordAndUrlSeed可產生更多關鍵字提案。如要封鎖整個網站，請使用
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 位數客戶 ID (string)，不含連字號。 |
seed (oneof) |
必填 | 請指定下列其中一項： • keyword_seed：keywords[] (1 到 20 個字串)。• url_seed：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_annotation 中要求 KEYWORD_CONCEPT 時填入；包含 concepts[] (name、concept_group.name 和 concept_group.type)。 |
aggregate_metric_results |
KeywordPlanAggregateMetricResults |
在 aggregate_metrics 中要求 DEVICE 時填入；包含 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()); } } }
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" )
小茹
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 要求和回應結構
以下範例使用 keywordAndUrlSeed、英文 (languageConstants/1000) 和美國 (geoTargetConstants/2840)，將 POST 要求傳送至 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"
]
}
}
成功的回應會在 results[] 中傳回 GenerateKeywordIdeaResult 列，以及歷史搜尋量和出價範圍：
{
"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 UI 中的關鍵字規劃工具：