Caution: You are viewing documentation for the API's REST interface. Most of our official client libraries use gRPC. See the REST Introduction for details.

Method: customers.keywordPlans.generateHistoricalMetrics

Returns the requested Keyword Plan historical metrics.

List of thrown errors: AuthenticationError AuthorizationError HeaderError InternalError KeywordPlanError QuotaError RequestError

HTTP request

POST https://googleads.googleapis.com/v13/{keywordPlan=customers/*/keywordPlans/*}:generateHistoricalMetrics

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
keywordPlan

string

Required. The resource name of the keyword plan of which historical metrics are requested.

Request body

The request body contains data with the following structure:

JSON representation 
{
  "aggregateMetrics": {
    object (KeywordPlanAggregateMetrics)
  },
  "historicalMetricsOptions": {
    object (HistoricalMetricsOptions)
  }
}
Fields
aggregateMetrics

object (KeywordPlanAggregateMetrics)

The aggregate fields to include in response.
historicalMetricsOptions

object (HistoricalMetricsOptions)

The options for historical metrics data.

Response body

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

Response message for KeywordPlanService.GenerateHistoricalMetrics.

JSON representation 
{
  "metrics": [
    {
      object (KeywordPlanKeywordHistoricalMetrics)
    }
  ],
  "aggregateMetricResults": {
    object (KeywordPlanAggregateMetricResults)
  }
}
Fields
metrics[]

object (KeywordPlanKeywordHistoricalMetrics)

List of keyword historical metrics.
aggregateMetricResults

object (KeywordPlanAggregateMetricResults)

The aggregate metrics for all the keywords in the keyword planner plan.

Authorization Scopes

Requires the following OAuth scope:

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

For more information, see the OAuth 2.0 Overview.

KeywordPlanKeywordHistoricalMetrics

A keyword historical metrics.

JSON representation 
{
  "closeVariants": [
    string
  ],
  "keywordMetrics": {
    object (KeywordPlanHistoricalMetrics)
  },
  "searchQuery": string
}
Fields
closeVariants[]

string

The list of close variant queries for searchQuery whose search results are combined into the searchQuery.
keywordMetrics

object (KeywordPlanHistoricalMetrics)

The historical metrics for the query associated with one or more ad_group_keywords in the plan.
searchQuery

string

The text of the query associated with one or more ad_group_keywords in the plan.

Note that we de-dupe your keywords list, eliminating close variants before returning the plan's keywords as text. For example, if your plan originally contained the keywords 'car' and 'cars', the returned search query will only contain 'cars'. Starting V5, the list of de-duped queries will be included in closeVariants field.