O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Gerar ideias de palavras-chave

Usando o KeywordPlanIdeaService, você pode descobrir sugestões de palavras-chave relevantes para sua campanha de pesquisa do Google ou recuperar métricas históricas de uma lista de palavras-chave.

Gerar ideias

Gere ideias de palavras-chave para uma campanha com KeywordPlanIdeaService.GenerateKeywordIdeas.

Você pode fornecer palavras-chave e URLs para gerar ideias. Defina parâmetros de segmentação, como locais, idioma e configurações de rede, para restringir a pesquisa. O serviço retorna estatísticas históricas, como dados de volume de pesquisa, para ajudar você a decidir se quer usar as palavras-chave na campanha. Para usuários familiarizados com a interface do Google Ads, isso é semelhante ao Planejador de palavras-chave.

Há várias maneiras de criar palavras-chave para gerar ideias:

Para palavras ou frases que descrevem o que você está anunciando, use KeywordSeed (requer pelo menos 1 e até 20 palavras-chave). Pode ser um tipo geral de empresa que você está segmentando, como encanadores, ou um produto ou serviço que você oferece, como limpeza de ralos.
Para o URL de uma página da Web ou de um site inteiro relacionado à sua empresa, use UrlSeed. A palavra-chave de URL segmenta apenas um URL específico. Se não houver correspondências, a pesquisa será expandida automaticamente para as páginas do mesmo domínio.

Para palavras-chave de URL, o serviço não usa o conteúdo de hiperlinks para gerar ideias de palavras-chave.
Para palavras-chave e URLs, use KeywordAndUrlSeed (requer de 1 a 20 palavras-chave e um URL).

O uso de KeywordAndUrlSeed pode resultar em um volume maior de ideias de palavras-chave em comparação com apenas UrlSeed.
Para um site inteiro, use SiteSeed. Dado um nome de domínio de nível superior, como www.example.com, a palavra-chave de site gera até 250.000 ideias de palavras-chave com base em informações disponíveis publicamente.

Para restringir a segmentação, você pode configurar language, local (até 10 geo_target_constants), keyword_plan_network, include_adult_keywords, keyword_annotation (Refinar palavras-chave), e historical_metrics_options.

A resposta oferece suporte à paginação (até 10.000 resultados por página). Sempre verifique next_page_token para determinar se há mais páginas disponíveis, já que uma página pode retornar menos resultados que page_size antes da página final. Cada GenerateKeywordIdeaResult retorna o text canônico (com close_variants), keyword_idea_metrics históricas para filtragem antes de gerar métricas de previsão e keyword_annotations opcionais.

Referência de campo de solicitação e resposta

Chame KeywordPlanIdeaService.GenerateKeywordIdeas no endpoint a seguir:

POST https://googleads.googleapis.com/v26/customers/{customer_id}:generateKeywordIdeas

A tabela a seguir resume os campos e restrições em GenerateKeywordIdeasRequest:

Campo de solicitação	Requisito	Formato e restrições
`customer_id`	Obrigatório	ID de cliente de 10 dígitos (`string`) sem hifens.
`seed` (`oneof`)	Obrigatório	Especifique uma destas opções: • `keyword_seed`: `keywords[]` (de 1 a 20 strings). • `url_seed`: `url` (URL de página específica). • `keyword_and_url_seed`: `url` mais de 1 a 20 `keywords[]`. • `site_seed`: `site` (nome de domínio como `www.example.com`, retornando até 250.000 ideias).
`language`	Opcional	Nome do recurso de critério de idioma (`languageConstants/{criterion_id}`, por exemplo, `languageConstants/1000` para inglês). Consulte Constantes de idioma. Se omitido, as palavras-chave em todos os idiomas serão incluídas.
`geo_target_constants[]`	Opcional	Até 10 nomes de recursos de local (`geoTargetConstants/{criterion_id}`, por exemplo, `geoTargetConstants/2840` para os Estados Unidos). Consulte Segmentações por área geográfica. Uma lista vazia segmenta todas as regiões geográficas.
`keyword_plan_network`	Opcional	`KeywordPlanNetwork` (`GOOGLE_SEARCH` ou `GOOGLE_SEARCH_AND_PARTNERS`). O padrão é `GOOGLE_SEARCH_AND_PARTNERS`.
`include_adult_keywords`	Opcional	`bool` que controla se as palavras-chave para adultos são retornadas. O padrão é `false`.
`keyword_annotation[]`	Opcional	Lista de `KeywordPlanKeywordAnnotation` valores (como `KEYWORD_CONCEPT`) para preencher `keyword_annotations` em cada resultado.
`aggregate_metrics`	Opcional	`KeywordPlanAggregateMetrics` com `aggregate_metric_types` definido como `DEVICE` para retornar contagens de pesquisa segmentadas por dispositivo em `aggregate_metric_results`.
`historical_metrics_options`	Opcional	`HistoricalMetricsOptions` que especifica um `year_month_range` opcional (disponível nos últimos quatro anos; o padrão é os últimos 12 meses) e `include_average_cpc`.
`page_size` e `page_token`	Opcional	Número máximo de resultados por página (`int32`, até `10,000`) e token de continuação de `next_page_token`. Mantenha todos os outros campos de solicitação idênticos em solicitações paginadas.

A mensagem GenerateKeywordIdeaResponse retorna os seguintes campos:

Campo de resposta	Tipo	Descrição
`results[].text`	`string`	Texto canônico da ideia de palavra-chave que representa a sugestão e suas `close_variants[]` combinadas.
`results[].close_variants[]`	`string[]`	Variantes aproximadas combinadas nesse `GenerateKeywordIdeaResult`.
`results[].keyword_idea_metrics`	`KeywordPlanHistoricalMetrics`	Volume de pesquisa `avg_monthly_searches` (média de 12 meses) e `monthly_search_volumes[]` (`year`, `month`, `monthly_searches`). Concorrência `competition` (`LOW`, `MEDIUM`, `HIGH`) e `competition_index` (`0` a `100`). Lances e CPC `low_top_of_page_bid_micros` (20º percentil), `high_top_of_page_bid_micros` (80º percentil) e `average_cpc_micros` (preenchido quando `include_average_cpc = true`).
`results[].keyword_annotations`	`KeywordAnnotations`	Preenchido quando `KEYWORD_CONCEPT` é solicitado em `keyword_annotation`; contém `concepts[]` (`name`, `concept_group.name` e `concept_group.type`).
`aggregate_metric_results`	`KeywordPlanAggregateMetricResults`	Preenchido quando `DEVICE` é solicitado em `aggregate_metrics`; contém `device_searches[]` (`MOBILE`, `TABLET`, `DESKTOP`).
`next_page_token` e `total_size`	`string`, `int64`	Token de continuação para a próxima página (omitido na última página) e contagem total de ideias de palavras-chave disponíveis.

Exemplo de código

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());
    }
  }
}GenerateKeywordIdeas.java

C#

public void Run(GoogleAdsClient client, long customerId, long[] locationIds,
    long languageId, string[] keywordTexts, string pageUrl)
{
    KeywordPlanIdeaServiceClient keywordPlanIdeaService =
        client.GetService(Services.V26.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;
    }
}GenerateKeywordIdeas.cs

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
        );
    }
}GenerateKeywordIdeas.php

Python

def main(
    client: GoogleAdsClient,
    customer_id: str,
    location_ids: list[str],
    language_id: str,
    keyword_texts: list[str],
    page_url: str,
):
    keyword_plan_idea_service: KeywordPlanIdeaServiceClient = (
        client.get_service("KeywordPlanIdeaService")
    )
    keyword_competition_level_enum: KeywordPlanCompetitionLevelEnum = (
        client.enums.KeywordPlanCompetitionLevelEnum
    )
    keyword_plan_network: KeywordPlanNetworkEnum = (
        client.enums.KeywordPlanNetworkEnum.GOOGLE_SEARCH_AND_PARTNERS
    )
    location_rns: list[str] = map_locations_ids_to_resource_names(
        client, location_ids
    )
    google_ads_service: GoogleAdsServiceClient = client.get_service(
        "GoogleAdsService"
    )
    language_rn: str = google_ads_service.language_constant_path(language_id)

    # Either keywords or a page_url are required to generate keyword ideas
    # so this raises an error if neither are provided.
    if not (keyword_texts or page_url):
        raise ValueError(
            "At least one of keywords or page URL is required, "
            "but neither was specified."
        )

    # Only one of the fields "url_seed", "keyword_seed", or
    # "keyword_and_url_seed" can be set on the request, depending on whether
    # keywords, a page_url or both were passed to this function.
    request: GenerateKeywordIdeasRequest = client.get_type(
        "GenerateKeywordIdeasRequest"
    )
    request.customer_id = customer_id
    request.language = language_rn
    request.geo_target_constants = location_rns
    request.include_adult_keywords = False
    request.keyword_plan_network = keyword_plan_network

    # To generate keyword ideas with only a page_url and no keywords we need
    # to initialize a UrlSeed object with the page_url as the "url" field.
    if not keyword_texts and page_url:
        request.url_seed.url = page_url

    # To generate keyword ideas with only a list of keywords and no page_url
    # we need to initialize a KeywordSeed object and set the "keywords" field
    # to be a list of StringValue objects.
    if keyword_texts and not page_url:
        request.keyword_seed.keywords.extend(keyword_texts)

    # To generate keyword ideas using both a list of keywords and a page_url we
    # need to initialize a KeywordAndUrlSeed object, setting both the "url" and
    # "keywords" fields.
    if keyword_texts and page_url:
        request.keyword_and_url_seed.url = page_url
        request.keyword_and_url_seed.keywords.extend(keyword_texts)

    keyword_ideas = keyword_plan_idea_service.generate_keyword_ideas(
        request=request
    )

    idea: GenerateKeywordIdeaResult
    for idea in keyword_ideas:
        competition_value = idea.keyword_idea_metrics.competition.name
        print(
            f'Keyword idea text "{idea.text}" has '
            f'"{idea.keyword_idea_metrics.avg_monthly_searches}" '
            f'average monthly searches and "{competition_value}" '
            "competition.\n"
        )generate_keyword_ideas.py

Ruby

def generate_keyword_ideas(customer_id, location_ids, language_id, keywords,
    page_url)
  # GoogleAdsClient will read a config file from
  # ENV['HOME']/google_ads_config.rb when called without parameters
  client = Google::Ads::GoogleAds::GoogleAdsClient.new

  # Make sure that keywords and/or page URL were specified. The request must
  # have exactly one of urlSeed, keywordSeed, or keywordAndUrlSeed set.
  if keywords.reject {|k| k.nil?}.empty? && page_url.nil?
    raise "At least one of keywords or page URL is required."
  end

  kp_idea_service = client.service.keyword_plan_idea

  options_hash = if keywords.empty?
                   seed = client.resource.url_seed do |seed|
                     seed.url = page_url
                   end
                   {url_seed: seed}
                 elsif page_url.nil?
                   seed = client.resource.keyword_seed do |seed|
                     keywords.each do |keyword|
                       seed.keywords << keyword
                     end
                   end
                   {keyword_seed: seed}
                 else
                   seed = client.resource.keyword_and_url_seed do |seed|
                     seed.url = page_url
                     keywords.each do |keyword|
                       seed.keywords << keyword
                     end
                   end
                   {keyword_and_url_seed: seed}
                 end

  geo_target_constants = location_ids.map do |location_id|
    client.path.geo_target_constant(location_id)
  end

  include_adult_keywords = true

  response = kp_idea_service.generate_keyword_ideas(
    customer_id: customer_id,
    language: client.path.language_constant(language_id),
    geo_target_constants: geo_target_constants,
    include_adult_keywords: include_adult_keywords,
    # To restrict to only Google Search, change the parameter below to
    # :GOOGLE_SEARCH
    keyword_plan_network: :GOOGLE_SEARCH_AND_PARTNERS,
    **options_hash
  )

  response.each do |result|
    monthly_searches = if result.keyword_idea_metrics.nil?
                         0
                       else
                         result.keyword_idea_metrics.avg_monthly_searches
                       end
    competition = if result.keyword_idea_metrics.nil?
                    :UNSPECIFIED
                  else
                    result.keyword_idea_metrics.competition
                  end
    puts "Keyword idea text #{result.text} has #{monthly_searches} average " +
        "monthly searches and competition as #{competition}."
  end
endgenerate_keyword_ideas.rb

Perl

sub generate_keyword_ideas {
  my (
    $api_client,  $customer_id,   $location_ids,
    $language_id, $keyword_texts, $page_url
  ) = @_;

  # Make sure that keywords and/or page URL were specified. The request must have
  # exactly one of urlSeed, keywordSeed, or keywordAndUrlSeed set.
  if (not scalar @$keyword_texts and not $page_url) {
    die "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.
  my $request_option_args = {};
  if (!scalar @$keyword_texts) {
    # Only page URL was specified, so use a UrlSeed.
    $request_option_args->{urlSeed} =
      Google::Ads::GoogleAds::V26::Services::KeywordPlanIdeaService::UrlSeed->
      new({
        url => $page_url
      });
  } elsif (not $page_url) {
    # Only keywords were specified, so use a KeywordSeed.
    $request_option_args->{keywordSeed} =
      Google::Ads::GoogleAds::V26::Services::KeywordPlanIdeaService::KeywordSeed
      ->new({
        keywords => $keyword_texts
      });
  } else {
    # Both page URL and keywords were specified, so use a KeywordAndUrlSeed.
    $request_option_args->{keywordAndUrlSeed} =
      Google::Ads::GoogleAds::V26::Services::KeywordPlanIdeaService::KeywordAndUrlSeed
      ->new({
        url      => $page_url,
        keywords => $keyword_texts
      });
  }

  # Create a list of geo target constants based on the resource name of specified
  # location IDs.
  my $geo_target_constants = [
    map (
      Google::Ads::GoogleAds::V26::Utils::ResourceNames::geo_target_constant(
        $_),
      @$location_ids)];

  # Generate keyword ideas based on the specified parameters.
  my $keyword_ideas_response =
    $api_client->KeywordPlanIdeaService()->generate_keyword_ideas({
      customerId => $customer_id,
      # Set the language resource using the provided language ID.
      language =>
        Google::Ads::GoogleAds::V26::Utils::ResourceNames::language_constant(
        $language_id),
      # Add the resource name of each location ID to the request.
      geoTargetConstants => $geo_target_constants,
      # Set the network. To restrict to only Google Search, change the parameter below
      # to GOOGLE_SEARCH.
      keywordPlanNetwork => GOOGLE_SEARCH_AND_PARTNERS,
      %$request_option_args
    });

  # Iterate over the results and print its detail.
  foreach my $result (@{$keyword_ideas_response->{results}}) {
    printf "Keyword idea text '%s' has %d average monthly searches " .
      "and '%s' competition.\n", $result->{text},
      $result->{keywordIdeaMetrics}{avgMonthlySearches}
      ? $result->{keywordIdeaMetrics}{avgMonthlySearches}
      : 0,
      $result->{keywordIdeaMetrics}{competition}
      ? $result->{keywordIdeaMetrics}{competition}
      : "undef";
  }

  return 1;
}generate_keyword_ideas.pl

curl

# This code example generates keyword ideas.
#
# Variables:
#   API_VERSION,
#   CUSTOMER_ID,
#   MANAGER_CUSTOMER_ID,
#   OAUTH2_ACCESS_TOKEN:
#     See https://developers.google.com/google-ads/api/rest/auth#request_headers
#     for details.
#
#   LANGUAGE: The resource name of the language to target. This is in the format
#     of "languageConstants/{criterion_id}". See
#     https://developers.google.com/google-ads/api/data/codes-formats#languages
#     for the available criterion_id values.
#   GEO_TARGET_CONSTANT: The resource name of the geo target constant to
#     generate keyword ideas for. This is in the format of
#     "geoTargetConstants/{criterion_id}". See
#     https://developers.google.com/google-ads/api/data/geotargets for the
#     available criterion_id values.
#   KEYWORD: The keyword to generate keyword ideas for.
#   URL: The URL of the website to generate keyword ideas for.
curl -f --request POST \
"https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}:generateKeywordIdeas" \
--header "Content-Type: application/json" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data @- <<EOF
{
  "language": "${LANGUAGE}",
  "geoTargetConstants": [
    "${GEO_TARGET_CONSTANT}"
  ],
  "includeAdultKeywords": false,
  "keywordPlanNetwork": "GOOGLE_SEARCH",
  "keywordAndUrlSeed": {
    "keywords": [
      "${KEYWORD}"
    ],
    "url": "${URL}"
  }
}
EOFgenerate_keyword_ideas.sh

Estrutura de solicitação e resposta REST

O exemplo a seguir envia uma solicitação POST para KeywordPlanIdeaService.GenerateKeywordIdeas usando keywordAndUrlSeed, inglês (languageConstants/1000) e os Estados Unidos (geoTargetConstants/2840):

POST https://googleads.googleapis.com/v26/customers/{customer_id}:generateKeywordIdeas

{
  "language": "languageConstants/1000",
  "geoTargetConstants": [
    "geoTargetConstants/2840"
  ],
  "includeAdultKeywords": false,
  "keywordPlanNetwork": "GOOGLE_SEARCH",
  "keywordAnnotation": [
    "KEYWORD_CONCEPT"
  ],
  "keywordAndUrlSeed": {
    "url": "https://www.example.com/mars-cruises",
    "keywords": [
      "mars cruise",
      "space vacation"
    ]
  }
}

Uma resposta bem-sucedida retorna GenerateKeywordIdeaResult linhas em results[] com o volume de pesquisa histórico e intervalos de lances:

{
  "results": [
    {
      "text": "mars cruise",
      "keywordIdeaMetrics": {
        "avgMonthlySearches": "12100",
        "competition": "MEDIUM",
        "competitionIndex": "54",
        "lowTopOfPageBidMicros": "1450000",
        "highTopOfPageBidMicros": "4800000",
        "monthlySearchVolumes": [
          {
            "year": "2026",
            "month": "MAY",
            "monthlySearches": "14800"
          }
        ]
      },
      "keywordAnnotations": {
        "concepts": [
          {
            "name": "Space Travel",
            "conceptGroup": {
              "name": "Travel",
              "type": "OTHERS"
            }
          }
        ]
      }
    }
  ],
  "totalSize": "1"
}

Mapear para a interface

A tabela a seguir mapeia os parâmetros KeywordPlanIdeaService.GenerateKeywordIdeas para o Planejador de palavras-chave na interface do Google Ads:

Planejador de palavras-chave na interface	API Google Ads
Inserir palavras-chave e URLs	`GenerateKeywordIdeasRequest.keyword_and_url_seed` `GenerateKeywordIdeasRequest.keyword_seed` `GenerateKeywordIdeasRequest.url_seed` `GenerateKeywordIdeasRequest.site_seed`
Locais	`GenerateKeywordIdeasRequest.geo_target_constants`
Palavras-chave para adultos	`GenerateKeywordIdeasRequest.include_adult_keywords`
Idioma	`GenerateKeywordIdeasRequest.language`
Redes de pesquisa	`GenerateKeywordIdeasRequest.keyword_plan_network`
Refinar palavras-chave	`GenerateKeywordIdeasRequest.keyword_annotation`
Período	`GenerateKeywordIdeasRequest.historical_metrics_options`
Resultados: palavra-chave	`GenerateKeywordIdeaResult.text`
Resultados: métricas	`GenerateKeywordIdeaResult.keyword_idea_metrics`

Visão geral

Avançar

Gerar temas de grupo de anúncios