Using the [`KeywordPlanIdeaService`](https://developers.google.com/google-ads/api/reference/rpc/v26/KeywordPlanIdeaService), you
can generate keywords within the same theme as existing keywords and ad groups.

For example, if the theme is `bakery`, the service generates keywords that can
trigger ads for searches such as `bakery near me`, `local bakery`, or `cake
shop`.

## Keyword organization suggestions

Organize keyword ideas (such as those discovered with
[`GenerateKeywordIdeas`](https://developers.google.com/google-ads/api/docs/keyword-planning/generate-keyword-ideas) or your own candidate list) for
existing ad groups with
[`KeywordPlanIdeaService.GenerateAdGroupThemes`](https://developers.google.com/google-ads/api/reference/rpc/v26/KeywordPlanIdeaService/GenerateAdGroupThemes). Rather than
manually grouping keyword suggestions into ad groups, you can automatically
assign keywords and match types to the best-matching target ad groups.

When constructing a [`GenerateAdGroupThemesRequest`](https://developers.google.com/google-ads/api/reference/rpc/v26/GenerateAdGroupThemesRequest), provide
the following required fields:

- [`customer_id`](https://developers.google.com/google-ads/api/reference/rpc/v26/GenerateAdGroupThemesRequest#customer_id): The ID of the customer for whom you are generating ad group themes.
- [`keywords`](https://developers.google.com/google-ads/api/reference/rpc/v26/GenerateAdGroupThemesRequest#keywords%5B%5D): A list of up to 10,000 seed keyword strings to organize.
- [`ad_groups`](https://developers.google.com/google-ads/api/reference/rpc/v26/GenerateAdGroupThemesRequest#ad_groups%5B%5D): A list of up to 10,000 existing ad group resource names (formatted as `customers/{customer_id}/adGroups/{ad_group_id}`) to consider as target themes.

The API returns a [`GenerateAdGroupThemesResponse`](https://developers.google.com/google-ads/api/reference/rpc/v26/GenerateAdGroupThemesResponse) containing:

- [`ad_group_keyword_suggestions`](https://developers.google.com/google-ads/api/reference/rpc/v26/GenerateAdGroupThemesResponse#ad_group_keyword_suggestions%5B%5D): A list of [`AdGroupKeywordSuggestion`](https://developers.google.com/google-ads/api/reference/rpc/v26/AdGroupKeywordSuggestion) objects. Each suggestion pairs `keyword_text` (along with the normalized `suggested_keyword_text`) and `suggested_match_type` (`BROAD`, `PHRASE`, or `EXACT`) with a `suggested_ad_group` and `suggested_campaign`.
- [`unusable_ad_groups`](https://developers.google.com/google-ads/api/reference/rpc/v26/GenerateAdGroupThemesResponse#unusable_ad_groups%5B%5D): A list of [`UnusableAdGroup`](https://developers.google.com/google-ads/api/reference/rpc/v26/UnusableAdGroup) objects identifying any input ad groups that the service cannot use as theme targets (for example, if the ad group is not `ENABLED` or belongs to a campaign that is neither `ENABLED` nor `PAUSED`).

Because `GenerateAdGroupThemes` does not mutate your account directly, you can:

1. Group the returned suggestions into [`ForecastAdGroup`](https://developers.google.com/google-ads/api/reference/rpc/v26/ForecastAdGroup) objects inside a [`CampaignToForecast`](https://developers.google.com/google-ads/api/reference/rpc/v26/CampaignToForecast) to estimate future traffic with [`GenerateKeywordForecastMetrics`](https://developers.google.com/google-ads/api/docs/keyword-planning/generate-forecast-metrics).
2. Apply the finalized suggestions to the target serving ad groups by creating [`AdGroupCriterion`](https://developers.google.com/google-ads/api/reference/rpc/v26/AdGroupCriterion) resources using [`AdGroupCriterionService.MutateAdGroupCriteria`](https://developers.google.com/google-ads/api/reference/rpc/v26/AdGroupCriterionService/MutateAdGroupCriteria).