AI-generated Key Takeaways
-
The KeywordPlanIdeaService can be used to find new keywords and historical metrics for Google Search campaigns.
-
Keyword ideas can be generated using keywords, a URL, or both as seeds.
-
Targeting parameters such as location, language, and network settings can be used to refine keyword idea generation.
-
Historical statistics like search volume data are provided with the results to help determine keyword usability.
-
This service offers similar functionality to the Keyword Planner tool in the Google Ads UI.
Using the KeywordPlanIdeaService
, you
can search for new keywords that are relevant to your Google Search campaign,
or find historical metrics on keywords.
Generate ideas
Generate keyword ideas for a campaign with KeywordPlanIdeaService.GenerateKeywordIdeas
.
You can provide keyword and URL seeds to generate ideas. Set targeting parameters such as locations, language, and network settings to narrow down your search. Historical statistics such as search volume data are returned to help you determine if you want to use the keywords for your campaign. For users familiar with the Google Ads UI, this is similar to Keyword Planner .
There are several ways you can create seeds for generating new keywords:
-
For words or phrases that describe what you're advertising, use
KeywordSeed. This could be a general type of business you are targeting such as plumbers, or it could be a product or service you offer such as drain cleaning. -
For the URL of a webpage or entire website related to your business, use
UrlSeed. The URL seed targets only a specific URL. If there are no hits, the search automatically expands up to the pages from the same domain.For URL seeds, the contents of hyperlinks are not used to generate keyword ideas.
-
For both keyword seeds and a URL seeds, use
KeywordAndUrlSeed.Using
KeywordAndUrlSeedcan result in a larger volume of keyword ideas, as compared to justUrlSeed. -
For an entire site, use
SiteSeed. Given a top-level domain name, such aswww.example.com, the site seed generates up to 250,000 keyword ideas from publicly available information.
To narrow down your targeting, you can:
- Set the language with
GenerateKeywordIdeasRequest.language. See Language Constants for valid IDs. - Set the location with
GenerateKeywordIdeasRequest.geo_target_constants. See Geo Targets for valid IDs. - Set the network with
GenerateKeywordIdeasRequest.keyword_plan_network. - Set whether to include adult keywords with
GenerateKeywordIdeasRequest.include_adult_keywords. - Refine keywords
with
GenerateKeywordIdeasRequest.keyword_annotation. - Set the date range with
GenerateKeywordIdeasRequest.historical_metrics_options.
The result set in the response supports pagination .
Ideas are returned with historical metrics which can be used to filter a list down to use with forecasts. For example, you might only want to target high search volumes to maximize the reach of your campaign, or you might want to target only higher competition scores to boost your awareness.
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 . V22 . 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 ); } }

