GenerateKeywordIdeas

  • The GenerateKeywordIdeas RPC method returns a list of keyword ideas.

  • This method requires the https://www.googleapis.com/auth/adwords OAuth scope for authorization.

  • Several errors can be thrown by this method, including AuthenticationError, AuthorizationError, InternalError, and QuotaError.

Returns a list of keyword ideas.

List of thrown errors: AuthenticationError AuthorizationError CollectionSizeError HeaderError InternalError KeywordPlanIdeaError QuotaError RequestError

HTTP request

POST https://googleads.googleapis.com/v22/customers/{customerId}:generateKeywordIdeas

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
customerId

string

The ID of the customer with the recommendation.

Request body

The request body contains data with the following structure:

JSON representation 
{
  "geoTargetConstants": [
    string
  ],
  "includeAdultKeywords": boolean,
  "pageToken": string,
  "pageSize": integer,
  "keywordPlanNetwork": enum (KeywordPlanNetwork),
  "keywordAnnotation": [
    enum (KeywordPlanKeywordAnnotation)
  ],
  "aggregateMetrics": {
    object (KeywordPlanAggregateMetrics)
  },
  "historicalMetricsOptions": {
    object (HistoricalMetricsOptions)
  },
  "language": string,

  // Union field seed can be only one of the following:
  "keywordAndUrlSeed": {
    object (KeywordAndUrlSeed)
  },
  "keywordSeed": {
    object (KeywordSeed)
  },
  "urlSeed": {
    object (UrlSeed)
  },
  "siteSeed": {
    object (SiteSeed)
  }
  // End of list of possible types for union field seed.
}
Fields
aggregateMetrics

object (KeywordPlanAggregateMetrics)

The aggregate fields to include in response.
geoTargetConstants[]

string

The resource names of the location to target. Maximum is 10. An empty list MAY be used to specify all targeting geos.
historicalMetricsOptions

object (HistoricalMetricsOptions)

The options for historical metrics data.
includeAdultKeywords

boolean

If true, adult keywords will be included in response. The default value is false.
keywordAnnotation[]

enum (KeywordPlanKeywordAnnotation)

The keyword annotations to include in response.
keywordPlanNetwork

enum (KeywordPlanNetwork)

Targeting network. If not set, Google Search And Partners Network will be used.
language

string

The resource name of the language to target. Each keyword belongs to some set of languages; a keyword is included if language is one of its languages. If not set, all keywords will be included.
pageSize

integer

Number of results to retrieve in a single page. A maximum of 10,000 results may be returned, if the pageSize exceeds this, it is ignored. If unspecified, at most 10,000 results will be returned. The server may decide to further limit the number of returned resources. If the response contains fewer than 10,000 results it may not be assumed as last page of results.
pageToken

string

Token of the page to retrieve. If not specified, the first page of results will be returned. To request next page of results use the value obtained from nextPageToken in the previous response. The request fields must match across pages.
seed. The type of seed to generate keyword ideas. seed can be only one of the following:
keywordAndUrlSeed

object (KeywordAndUrlSeed)

A Keyword and a specific Url to generate ideas from for example, cars, www.example.com/cars.
keywordSeed

object (KeywordSeed)

A Keyword or phrase to generate ideas from, for example, cars.
siteSeed

object (SiteSeed)

The site to generate ideas from, for example, www.example.com.
urlSeed

object (UrlSeed)

A specific url to generate ideas from, for example, www.example.com/cars.

Response body

Response message for KeywordPlanIdeaService.GenerateKeywordIdeas.

If successful, the response body contains data with the following structure:

JSON representation 
{
  "results": [
    {
      object (GenerateKeywordIdeaResult)
    }
  ],
  "aggregateMetricResults": {
    object (KeywordPlanAggregateMetricResults)
  },
  "nextPageToken": string,
  "totalSize": string
}
Fields
aggregateMetricResults

object (KeywordPlanAggregateMetricResults)

The aggregate metrics for all keyword ideas.
nextPageToken

string

Pagination token used to retrieve the next page of results. Pass the content of this string as the pageToken attribute of the next request. nextPageToken is not returned for the last page.
results[]

object (GenerateKeywordIdeaResult)

Results of generating keyword ideas.
totalSize

string (int64 format)

Total number of results available.

KeywordPlanKeywordAnnotation

Enumerates keyword plan annotations that can be requested.

Enums
KEYWORD_CONCEPT Return the keyword concept and concept group data.
UNKNOWN The value is unknown in this version.
UNSPECIFIED Not specified.

KeywordAndUrlSeed

Keyword And Url Seed

JSON representation 
{
  "keywords": [
    string
  ],
  "url": string
}
Fields
keywords[]

string

Requires at least one keyword and no more than 20 keywords.
url

string

The URL to crawl in order to generate keyword ideas.

KeywordSeed

Keyword Seed

JSON representation 
{
  "keywords": [
    string
  ]
}
Fields
keywords[]

string

Requires at least one keyword and no more than 20 keywords.

UrlSeed

Url Seed

JSON representation 
{
  "url": string
}
Fields
url

string

The URL to crawl in order to generate keyword ideas.

SiteSeed

Site Seed

JSON representation 
{
  "site": string
}
Fields
site

string

The domain name of the site. If the customer requesting the ideas doesn't own the site provided only public information is returned.

GenerateKeywordIdeaResult

The result of generating keyword ideas.

JSON representation 
{
  "keywordIdeaMetrics": {
    object (KeywordPlanHistoricalMetrics)
  },
  "keywordAnnotations": {
    object (KeywordAnnotations)
  },
  "closeVariants": [
    string
  ],
  "text": string
}
Fields
closeVariants[]

string

The list of close variants from the requested keywords that are combined into this GenerateKeywordIdeaResult. See https://support.google.com/google-ads/answer/9342105 for the definition of "close variants".
keywordAnnotations

object (KeywordAnnotations)

The annotations for the keyword. The annotation data is only provided if requested.
keywordIdeaMetrics

object (KeywordPlanHistoricalMetrics)

The historical metrics for the keyword.
text

string

Text of the keyword idea. As in Keyword Plan historical metrics, this text may not be an actual keyword, but the canonical form of multiple keywords. See KeywordPlanKeywordHistoricalMetrics message in KeywordPlanService.

KeywordAnnotations

The annotations for the keyword plan keywords.

JSON representation 
{
  "concepts": [
    {
      object (KeywordConcept)
    }
  ]
}
Fields
concepts[]

object (KeywordConcept)

The list of concepts for the keyword.

KeywordConcept

The concept for the keyword.

JSON representation 
{
  "name": string,
  "conceptGroup": {
    object (ConceptGroup)
  }
}
Fields
conceptGroup

object (ConceptGroup)

The concept group of the concept details.
name

string

The concept name for the keyword in the conceptGroup.

ConceptGroup

The concept group for the keyword concept.

JSON representation 
{
  "name": string,
  "type": enum (KeywordPlanConceptGroupType)
}
Fields
name

string

The concept group name.
type

enum (KeywordPlanConceptGroupType)

The concept group type.

KeywordPlanConceptGroupType

Enumerates keyword plan concept group types.

Enums
BRAND The concept group classification is based on BRAND.
NON_BRAND These concept group classification is not based on BRAND. This is returned for generic keywords that don't have a brand association.
OTHER_BRANDS The concept group classification based on BRAND, that didn't fit well with the BRAND classifications. These are generally outliers and can have very few keywords in this type of classification.
UNKNOWN The value is unknown in this version.
UNSPECIFIED The concept group classification different from brand/non-brand. This is a catch all bucket for all classifications that are none of the below.
Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/adwords

For more information, see the OAuth 2.0 Overview.