---
title: "POST /v23/customers/{customersId}:generateKeywordIdeas"
method: POST
path: "/v23/customers/{customersId}:generateKeywordIdeas"
tags: ["customers"]
---

# POST /v23/customers/{customersId}:generateKeywordIdeas

`POST /v23/customers/{customersId}:generateKeywordIdeas`

## Request

- Base URL: `https://searchads360.googleapis.com`
- URL: `https://searchads360.googleapis.com/v23/customers/{customersId}:generateKeywordIdeas`
- Auth: OAuth 2 and OAuth 2
  - Implicit: `https://accounts.google.com/o/oauth2/auth`
  - Scopes: `https://www.googleapis.com/auth/doubleclicksearch`
  - Authorization code: `https://accounts.google.com/o/oauth2/auth`
  - Token URL: `https://accounts.google.com/o/oauth2/token` scopes: `https://www.googleapis.com/auth/doubleclicksearch`
- TypeScript: <https://skmtc.dev/google/apis/searchads360/docs/v23/customers/:customersId:generateKeywordIdeas/post.ts> (a function with typed inputs; its response is checked against the schema)

Returns a list of keyword ideas. List of thrown errors: [AuthenticationError]() [AuthorizationError]() [CollectionSizeError]() [HeaderError]() [InternalError]() [KeywordPlanIdeaError]() [QuotaError]() [RequestError]()

## Path parameters

- `customersId` string, required

## Request body

- GoogleAdsSearchads360V23ServicesGenerateKeywordIdeasRequest: Request message for KeywordPlanIdeaService.GenerateKeywordIdeas.
  - `aggregateMetrics` GoogleAdsSearchads360V23CommonKeywordPlanAggregateMetrics: The aggregate metrics specification of the request.
    - `aggregateMetricTypes` string[]: The list of aggregate metrics to fetch data.
  - `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` GoogleAdsSearchads360V23CommonHistoricalMetricsOptions: Historical metrics options.
    - `includeAverageCpc` boolean: Indicates whether to include average cost per click value. Average CPC is provided only for legacy support.
    - `yearMonthRange` GoogleAdsSearchads360V23CommonYearMonthRange: The year month range inclusive of the start and end months. Eg: A year month range to represent Jan 2020 would be: (Jan 2020, Jan 2020).
      - `end` GoogleAdsSearchads360V23CommonYearMonth: Year month.
        - `month` 'UNSPECIFIED' | 'UNKNOWN' | 'JANUARY' | 'FEBRUARY' | 'MARCH' | 'APRIL' | 'MAY' | 'JUNE' | 'JULY' | 'AUGUST' | 'SEPTEMBER' | 'OCTOBER' | 'NOVEMBER' | 'DECEMBER': The month of the year. (for example, FEBRUARY).
        - `year` string, int64: The year (for example, 2020).
      - `start` GoogleAdsSearchads360V23CommonYearMonth: Year month.
        - `month` 'UNSPECIFIED' | 'UNKNOWN' | 'JANUARY' | 'FEBRUARY' | 'MARCH' | 'APRIL' | 'MAY' | 'JUNE' | 'JULY' | 'AUGUST' | 'SEPTEMBER' | 'OCTOBER' | 'NOVEMBER' | 'DECEMBER': The month of the year. (for example, FEBRUARY).
        - `year` string, int64: The year (for example, 2020).
  - `includeAdultKeywords` boolean: If true, adult keywords will be included in response. The default value is false.
  - `keywordAndUrlSeed` GoogleAdsSearchads360V23ServicesKeywordAndUrlSeed: Keyword And Url Seed
    - `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.
  - `keywordAnnotation` string[]: The keyword annotations to include in response.
  - `keywordPlanNetwork` 'UNSPECIFIED' | 'UNKNOWN' | 'GOOGLE_SEARCH' | 'GOOGLE_SEARCH_AND_PARTNERS': Targeting network. If not set, Google Search And Partners Network will be used.
  - `keywordSeed` GoogleAdsSearchads360V23ServicesKeywordSeed: Keyword Seed
    - `keywords` string[]: Requires at least one keyword and no more than 20 keywords.
  - `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 page_size 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 `next_page_token` in the previous response. The request fields must match across pages.
  - `siteSeed` GoogleAdsSearchads360V23ServicesSiteSeed: Site Seed
    - `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.
  - `urlSeed` GoogleAdsSearchads360V23ServicesUrlSeed: Url Seed
    - `url` string: The URL to crawl in order to generate keyword ideas.

## Response `200`

Successful response

- GoogleAdsSearchads360V23ServicesGenerateKeywordIdeaResponse: Response message for KeywordPlanIdeaService.GenerateKeywordIdeas.
  - `aggregateMetricResults` GoogleAdsSearchads360V23CommonKeywordPlanAggregateMetricResults: The aggregated historical metrics for keyword plan keywords.
    - `deviceSearches` GoogleAdsSearchads360V23CommonKeywordPlanDeviceSearches[]: The aggregate searches for all the keywords segmented by device for the specified time. Supports the following device types: MOBILE, TABLET, DESKTOP. This is only set when KeywordPlanAggregateMetricTypeEnum.DEVICE is set in the KeywordPlanAggregateMetrics field in the request.
      - `device` 'UNSPECIFIED' | 'UNKNOWN' | 'MOBILE' | 'TABLET' | 'DESKTOP' | 'CONNECTED_TV' | 'OTHER': The device type.
      - `searchCount` string, int64: The total searches for the device.
  - `nextPageToken` string: Pagination token used to retrieve the next page of results. Pass the content of this string as the `page_token` attribute of the next request. `next_page_token` is not returned for the last page.
  - `results` GoogleAdsSearchads360V23ServicesGenerateKeywordIdeaResult[]: Results of generating keyword ideas.
    - `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` GoogleAdsSearchads360V23CommonKeywordAnnotations: The annotations for the keyword plan keywords.
      - `concepts` GoogleAdsSearchads360V23CommonKeywordConcept[]: The list of concepts for the keyword.
        - `conceptGroup` GoogleAdsSearchads360V23CommonConceptGroup: The concept group for the keyword concept.
          - `name` string: The concept group name.
          - `type` 'UNSPECIFIED' | 'UNKNOWN' | 'BRAND' | 'OTHER_BRANDS' | 'NON_BRAND': The concept group type.
        - `name` string: The concept name for the keyword in the concept_group.
    - `keywordIdeaMetrics` GoogleAdsSearchads360V23CommonKeywordPlanHistoricalMetrics: Historical metrics specific to the targeting options selected. Targeting options include geographies, network, and so on. Refer to https://support.google.com/google-ads/answer/3022575 for more details.
      - `averageCpcMicros` string, int64: Average Cost Per Click in micros for the keyword.
      - `avgMonthlySearches` string, int64: Approximate number of monthly searches on this query, averaged for the past 12 months.
      - `competition` 'UNSPECIFIED' | 'UNKNOWN' | 'LOW' | 'MEDIUM' | 'HIGH': The competition level for the query.
      - `competitionIndex` string, int64: The competition index for the query in the range [0, 100]. Shows how competitive ad placement is for a keyword. The level of competition from 0-100 is determined by the number of ad slots filled divided by the total number of ad slots available. If not enough data is available, null is returned.
      - `highTopOfPageBidMicros` string, int64: Top of page bid high range (80th percentile) in micros for the keyword.
      - `lowTopOfPageBidMicros` string, int64: Top of page bid low range (20th percentile) in micros for the keyword.
      - `monthlySearchVolumes` GoogleAdsSearchads360V23CommonMonthlySearchVolume[]: Approximate number of searches on this query for the past twelve months.
        - `month` 'UNSPECIFIED' | 'UNKNOWN' | 'JANUARY' | 'FEBRUARY' | 'MARCH' | 'APRIL' | 'MAY' | 'JUNE' | 'JULY' | 'AUGUST' | 'SEPTEMBER' | 'OCTOBER' | 'NOVEMBER' | 'DECEMBER': The month of the search volume.
        - `monthlySearches` string, int64: Approximate number of searches for the month. A null value indicates the search volume is unavailable for that month.
        - `year` string, int64: The year of the search volume (for example, 2020).
    - `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.
  - `totalSize` string, int64: Total number of results available.

---

[API](https://skmtc.dev/google/apis/searchads360.md) - [All operations](https://skmtc.dev/google/apis/searchads360/llms.txt) - [OpenAPI document](https://skmtc.dev/google/apis/searchads360/revisions/4a4511f84b18?raw)