[Forecast metrics](https://support.google.com/google-ads/answer/3022575) provide
estimated performance metrics ([`KeywordForecastMetrics`](https://developers.google.com/google-ads/api/reference/rpc/v26/KeywordForecastMetrics.md.txt)) for
proposed or existing campaigns. Available forecast metrics depend on your
supported API version and bidding strategy:

- **v24 and later** :
  - `clicks` (clicks): Returned only when using [`ManualCpcBiddingStrategy`](https://developers.google.com/google-ads/api/reference/rpc/v26/ManualCpcBiddingStrategy.md.txt) or [`MaximizeClicksBiddingStrategy`](https://developers.google.com/google-ads/api/reference/rpc/v26/MaximizeClicksBiddingStrategy.md.txt).
  - `cost_micros` (cost): Total forecasted cost in micros.
  - `average_cpc_micros` (average cost-per-click): Returned only when using [`ManualCpcBiddingStrategy`](https://developers.google.com/google-ads/api/reference/rpc/v26/ManualCpcBiddingStrategy.md.txt) or [`MaximizeClicksBiddingStrategy`](https://developers.google.com/google-ads/api/reference/rpc/v26/MaximizeClicksBiddingStrategy.md.txt) and `clicks > 0`.
  - `conversions` (conversions): Returned only when using [`MaximizeConversionsBiddingStrategy`](https://developers.google.com/google-ads/api/reference/rpc/v26/MaximizeConversionsBiddingStrategy.md.txt).
  - `average_cpa_micros` (average cost-per-acquisition): Returned only when using [`MaximizeConversionsBiddingStrategy`](https://developers.google.com/google-ads/api/reference/rpc/v26/MaximizeConversionsBiddingStrategy.md.txt) (calculated as `cost_micros / conversions`).
- **v23 and earlier** :
  - In addition to `clicks`, `cost_micros`, `average_cpc_micros`, `conversions`, and `average_cpa_micros` (returned across all bidding strategies), [`KeywordForecastMetrics`](https://developers.google.com/google-ads/api/reference/rpc/v23/KeywordForecastMetrics.md.txt) also returns [`impressions`](https://developers.google.com/google-ads/api/reference/rpc/v23/KeywordForecastMetrics.md.txt#impressions) (impressions), [`click_through_rate`](https://developers.google.com/google-ads/api/reference/rpc/v23/KeywordForecastMetrics.md.txt#click_through_rate) (click-through rate), and [`conversion_rate`](https://developers.google.com/google-ads/api/reference/rpc/v23/KeywordForecastMetrics.md.txt#conversion_rate) (conversion rate).

Experiment with different campaign configurations to optimize each of these
metrics. The forecast uses data such as historical quality score and
click-through rate to simulate expected performance.

Forecast metrics are typically used after discovering candidate keywords with
[keyword ideas](https://developers.google.com/google-ads/api/docs/keyword-planning/generate-keyword-ideas.md.txt) or filtering an
existing keyword list with
[historical metrics](https://developers.google.com/google-ads/api/docs/keyword-planning/generate-historical-metrics.md.txt), and
optionally grouping those keywords with
[ad group themes](https://developers.google.com/google-ads/api/docs/keyword-planning/generate-ad-group-themes.md.txt). While
historical metrics narrow down a large set of candidate keywords based on past
search volume, forecast metrics simulate future performance so you can optimize
your bids, daily budget, and targeting before updating a serving campaign.

## Generate metrics

To generate forecast metrics, complete these steps:

1. Construct a [`CampaignToForecast`](https://developers.google.com/google-ads/api/reference/rpc/v26/CampaignToForecast.md.txt) object that represents the campaign configuration, [`ForecastAdGroup`](https://developers.google.com/google-ads/api/reference/rpc/v26/ForecastAdGroup.md.txt) objects, and bidding strategy you want to evaluate.
2. Call [`KeywordPlanIdeaService.GenerateKeywordForecastMetrics`](https://developers.google.com/google-ads/api/reference/rpc/v26/KeywordPlanIdeaService/GenerateKeywordForecastMetrics.md.txt) with that `CampaignToForecast` and an optional [`forecast_period`](https://developers.google.com/google-ads/api/reference/rpc/v26/GenerateKeywordForecastMetricsRequest.md.txt#forecast_period) (whose start date must be in the future and end date within one year from today; if omitted, it defaults to next Sunday through the following Saturday in the customer account's timezone).
3. Read the campaign-level [`KeywordForecastMetrics`](https://developers.google.com/google-ads/api/reference/rpc/v26/KeywordForecastMetrics.md.txt) from the [`campaign_forecast_metrics`](https://developers.google.com/google-ads/api/reference/rpc/v26/GenerateKeywordForecastMetricsResponse.md.txt#campaign_forecast_metrics) field of [`GenerateKeywordForecastMetricsResponse`](https://developers.google.com/google-ads/api/reference/rpc/v26/GenerateKeywordForecastMetricsResponse.md.txt).

### Create a campaign to forecast

Here are some tips when creating your campaign to forecast:

- Create the ad groups based on themes such as creative relevance, product category, or cost-per-click (or use suggestions from [`GenerateAdGroupThemes`](https://developers.google.com/google-ads/api/docs/keyword-planning/generate-ad-group-themes.md.txt)).
- In **v23 and earlier** , include common negative keywords using [`CampaignToForecast.negative_keywords`](https://developers.google.com/google-ads/api/reference/rpc/v23/CampaignToForecast.md.txt#negative_keywords%5B%5D) or [`ForecastAdGroup.negative_keywords`](https://developers.google.com/google-ads/api/reference/rpc/v23/ForecastAdGroup.md.txt#negative_keywords%5B%5D) (for example, if you aren't in recruitment, exclude the keyword `'jobs'`). In **v24 and later** , `negative_keywords` is removed.
- Use an account that is related to the campaign. Don't forecast from an unrelated account. Google factors in quality score and creative content into the forecast.
- If a campaign is unrelated to the rest of your account, use a new clean account for the forecast.
- Repeat forecasts with different horizons to get a holistic picture.

### Version differences

In **v24 and later** , `CampaignToForecast`, `ForecastAdGroup`, and
`KeywordForecastMetrics` use a streamlined schema compared to **v23 and
earlier**, as shown in the following table:

| Feature | v24 and later | v23 and earlier |
|---|---|---|
| Ad group keywords | [`ForecastAdGroup.keywords`](https://developers.google.com/google-ads/api/reference/rpc/v26/ForecastAdGroup.md.txt#keywords[]) (`repeated KeywordInfo`) | [`ForecastAdGroup.biddable_keywords`](https://developers.google.com/google-ads/api/reference/rpc/v23/ForecastAdGroup.md.txt#biddable_keywords[]) (`repeated` [`BiddableKeyword`](https://developers.google.com/google-ads/api/reference/rpc/v23/BiddableKeyword.md.txt)) |
| Location targeting | [`CampaignToForecast.geo_target_constants`](https://developers.google.com/google-ads/api/reference/rpc/v26/CampaignToForecast.md.txt#geo_target_constants[]) (`repeated string` resource names) | [`CampaignToForecast.geo_modifiers`](https://developers.google.com/google-ads/api/reference/rpc/v23/CampaignToForecast.md.txt#geo_modifiers[]) (`repeated` [`CriterionBidModifier`](https://developers.google.com/google-ads/api/reference/rpc/v23/CriterionBidModifier.md.txt) with optional bid multipliers) |
| Search network targeting | Not specified on `CampaignToForecast` (defaults to Google Search) | Required [`CampaignToForecast.keyword_plan_network`](https://developers.google.com/google-ads/api/reference/rpc/v23/CampaignToForecast.md.txt#keyword_plan_network) |
| Negative keywords | Not supported on `CampaignToForecast` or `ForecastAdGroup` | Supported using [`CampaignToForecast.negative_keywords`](https://developers.google.com/google-ads/api/reference/rpc/v23/CampaignToForecast.md.txt#negative_keywords[]) and [`ForecastAdGroup.negative_keywords`](https://developers.google.com/google-ads/api/reference/rpc/v23/ForecastAdGroup.md.txt#negative_keywords[]) |
| Ad group and keyword CPC bid overrides | Configured only at the campaign bidding strategy level ([`ManualCpcBiddingStrategy.max_cpc_bid_micros`](https://developers.google.com/google-ads/api/reference/rpc/v26/ManualCpcBiddingStrategy.md.txt#max_cpc_bid_micros) or [`MaximizeClicksBiddingStrategy.max_cpc_bid_ceiling_micros`](https://developers.google.com/google-ads/api/reference/rpc/v26/MaximizeClicksBiddingStrategy.md.txt#max_cpc_bid_ceiling_micros)) | Can also be overridden per ad group ([`ForecastAdGroup.max_cpc_bid_micros`](https://developers.google.com/google-ads/api/reference/rpc/v23/ForecastAdGroup.md.txt#max_cpc_bid_micros)) or per keyword ([`BiddableKeyword.max_cpc_bid_micros`](https://developers.google.com/google-ads/api/reference/rpc/v23/BiddableKeyword.md.txt#max_cpc_bid_micros)) |
| Custom expected conversion rate | Not supported on `CampaignToForecast` | Optional [`CampaignToForecast.conversion_rate`](https://developers.google.com/google-ads/api/reference/rpc/v23/CampaignToForecast.md.txt#conversion_rate) |
| Returned forecast metrics | `clicks` and `average_cpc_micros` (Manual CPC or Maximize Clicks only), `cost_micros`, `conversions` and `average_cpa_micros` (Maximize Conversions only) | Returns `clicks`, `cost_micros`, `average_cpc_micros`, `conversions`, and `average_cpa_micros` across all bidding strategies, plus [`impressions`](https://developers.google.com/google-ads/api/reference/rpc/v23/KeywordForecastMetrics.md.txt#impressions), [`click_through_rate`](https://developers.google.com/google-ads/api/reference/rpc/v23/KeywordForecastMetrics.md.txt#click_through_rate), and [`conversion_rate`](https://developers.google.com/google-ads/api/reference/rpc/v23/KeywordForecastMetrics.md.txt#conversion_rate) |

### Code example

The next code example makes a request to
[`KeywordPlanIdeaService.GenerateKeywordForecastMetrics`](https://developers.google.com/google-ads/api/reference/rpc/v26/KeywordPlanIdeaService/GenerateKeywordForecastMetrics.md.txt). It
constructs an inline `CampaignToForecast` with ad groups and keywords, and then
displays the returned `campaign_forecast_metrics`.


### Java

```java
private void runExample(GoogleAdsClient googleAdsClient, Long customerId) {
  CampaignToForecast campaignToForecast = createCampaignToForecast(googleAdsClient);
  GenerateKeywordForecastMetricsRequest request =
      GenerateKeywordForecastMetricsRequest.newBuilder()
          .setCustomerId(String.valueOf(customerId))
          .setCampaign(campaignToForecast)
          .setForecastPeriod(
              DateRange.newBuilder()
                  // Sets the forecast start date to tomorrow.
                  .setStartDate(new DateTime().plusDays(1).toString("yyyy-MM-dd"))
                  // Sets the forecast end date to 30 days from today.
                  .setEndDate(new DateTime().plusDays(30).toString("yyyy-MM-dd")))
          .build();
  try (KeywordPlanIdeaServiceClient keywordPlanIdeaServiceClient =
      googleAdsClient.getLatestVersion().createKeywordPlanIdeaServiceClient()) {
    GenerateKeywordForecastMetricsResponse response =
        keywordPlanIdeaServiceClient.generateKeywordForecastMetrics(request);
    KeywordForecastMetrics metrics = response.getCampaignForecastMetrics();
    System.out.printf(
        "Estimated daily clicks: %s%n", metrics.hasClicks() ? metrics.getClicks() : null);
    System.out.printf(
        "Estimated average CPC (micros): %s%n",
        metrics.hasAverageCpcMicros() ? metrics.getAverageCpcMicros() : null);
  }
}

/**
 * Creates the campaign to forecast. A campaign to forecast lets you try out various
 * configurations and keywords to find the best optimization for your future campaigns. Once
 * you've found the best campaign configuration, create a serving campaign in your Google Ads
 * account with similar values and keywords. For more details, see:
 *
 * <p>https://support.google.com/google-ads/answer/3022575
 */
private CampaignToForecast createCampaignToForecast(GoogleAdsClient googleAdsClient) {
  CampaignToForecast.Builder campaignToForecastBuilder =
      CampaignToForecast.newBuilder()
          .setBiddingStrategy(
              CampaignBiddingStrategy.newBuilder()
                  .setManualCpcBiddingStrategy(
                      ManualCpcBiddingStrategy.newBuilder().setMaxCpcBidMicros(1_000_000L)));

  // See https://developers.google.com/google-ads/api/reference/data/geotargets for the list of
  // geo target IDs. Geo target constant 2840 is for USA.
  campaignToForecastBuilder.addGeoTargetConstants(ResourceNames.geoTargetConstant(2840));

  // See https://developers.google.com/google-ads/api/reference/data/codes-formats#languages for
  // the list of language criteria IDs. Language constant 1000 is for English.
  campaignToForecastBuilder.addLanguageConstants(ResourceNames.languageConstant(1000));

  // Create forecast ad group based on themes such as creative relevance, product category, or
  // cost per click.
  ForecastAdGroup.Builder forecastAdGroupBuilder = ForecastAdGroup.newBuilder();
  forecastAdGroupBuilder.addKeywords(
      KeywordInfo.newBuilder()
          .setText("mars cruise")
          .setMatchType(KeywordMatchType.BROAD));

  forecastAdGroupBuilder.addKeywords(
      KeywordInfo.newBuilder()
          .setText("cheap cruise")
          .setMatchType(KeywordMatchType.PHRASE));

  forecastAdGroupBuilder.addKeywords(
      KeywordInfo.newBuilder()
          .setText("jupiter cruise")
          .setMatchType(KeywordMatchType.BROAD));

  campaignToForecastBuilder.addAdGroups(forecastAdGroupBuilder.build());
  return campaignToForecastBuilder.build();
}
      
```

### C#

```c#
public void Run(GoogleAdsClient client, long customerId)
{
    CampaignToForecast campaignToForecast = CreateCampaignToForecast();

    KeywordPlanIdeaServiceClient keywordPlanIdeaService =
            client.GetService(Services.V26.KeywordPlanIdeaService);

    GenerateKeywordForecastMetricsRequest request = new GenerateKeywordForecastMetricsRequest()
    {
        CustomerId = customerId.ToString(),
        Campaign = campaignToForecast,
        ForecastPeriod = new DateRange()
        {
            // Set the forecast start date to tomorrow.
            StartDate = DateTime.Now.AddDays(1).ToString("yyyy-MM-dd"),
            // Set the forecast end date to 30 days from today.
            EndDate = DateTime.Now.AddDays(30).ToString("yyyy-MM-dd"),
        }
    };

    try
    {
        GenerateKeywordForecastMetricsResponse response =
            keywordPlanIdeaService.GenerateKeywordForecastMetrics(request);

        KeywordForecastMetrics metrics = response.CampaignForecastMetrics;

        Console.WriteLine($"Estimated daily clicks: {metrics.Clicks}.");            
        Console.WriteLine($"Estimated average cpc (micros): {metrics.AverageCpcMicros}.");
    }
    catch (GoogleAdsException e)
    {
        Console.WriteLine("Failure:");
        Console.WriteLine($"Message: {e.Message}");
        Console.WriteLine($"Failure: {e.Failure}");
        Console.WriteLine($"Request ID: {e.RequestId}");
        throw;
    }
}

/// <summary>
/// Creates the campaign to forecast. A campaign to forecast lets you try out
/// various configuration and keywords to find the best optimization for your
/// future campaigns. Once you've found the best campaign configuration,
/// create a serving campaign in your Google Ads account with similar values
/// and keywords. For more details, see:
/// https://support.google.com/google-ads/answer/3022575
/// </summary>
private CampaignToForecast CreateCampaignToForecast()
{
    CampaignToForecast campaignToForecast = new CampaignToForecast()
    {            
        BiddingStrategy = new CampaignToForecast.Types.CampaignBiddingStrategy()
        {
            ManualCpcBiddingStrategy = new ManualCpcBiddingStrategy()
            {
                MaxCpcBidMicros = 1_000_000
            }
        }
    };

    // See https://developers.google.com/google-ads/api/reference/data/geotargets
    // for the list of geo target IDs.
    // Geo target constant 2840 is for USA.
    campaignToForecast.GeoTargetConstants.Add(
        ResourceNames.GeoTargetConstant(2840)
    );

    // See https://developers.google.com/google-ads/api/reference/data/codes-formats#languages
    // for the list of language criteria IDs.
    // Language constant 1000 is for English.
    campaignToForecast.LanguageConstants.Add(ResourceNames.LanguageConstant(1000));

    // Create forecast ad group based on themes such as creative relevance, product category,
    // or cost per click.
    ForecastAdGroup forecastAdGroup = new ForecastAdGroup();

    KeywordInfo keyword1 = new KeywordInfo()
    {
        Text = "mars cruise",
        MatchType = KeywordMatchType.Broad
    };
    forecastAdGroup.Keywords.Add(keyword1);

    KeywordInfo keyword2 = new KeywordInfo()
    {
        Text = "cheap cruise",
        MatchType = KeywordMatchType.Phrase
    };
    forecastAdGroup.Keywords.Add(keyword2);

    KeywordInfo keyword3 = new KeywordInfo()
    {
        Text = "jupiter cruise",
        MatchType = KeywordMatchType.Exact
    };
    forecastAdGroup.Keywords.Add(keyword3);

    campaignToForecast.AdGroups.Add(forecastAdGroup);

    return campaignToForecast;
}
      
```

### PHP

```php
public static function runExample(
    GoogleAdsClient $googleAdsClient,
    int $customerId
): void {
    $campaignToForecast = self::createCampaignToForecast();
    $keywordPlanIdeaServiceClient = $googleAdsClient->getKeywordPlanIdeaServiceClient();
    // Generates keyword forecast metrics based on the specified parameters.
    $response = $keywordPlanIdeaServiceClient->generateKeywordForecastMetrics(
        new GenerateKeywordForecastMetricsRequest([
            'customer_id' => $customerId,
            'campaign' => $campaignToForecast,
            'forecast_period' => new DateRange([
                // Sets the forecast start date to tomorrow.
                'start_date' => date('Ymd', strtotime('+1 day')),
                // Sets the forecast end date to 30 days from today.
                'end_date' => date('Ymd', strtotime('+30 days'))
            ])
        ])
    );

    $metrics = $response->getCampaignForecastMetrics();
    printf(
        "Estimated daily clicks: %s%s",
        $metrics->hasClicks() ? sprintf("%.2f", $metrics->getClicks()) : "'none'",
        PHP_EOL
    );
    printf(
        "Estimated daily impressions: %s%s",
        $metrics->hasImpressions() ? sprintf("%.2f", $metrics->getImpressions()) : "'none'",
        PHP_EOL
    );
    printf(
        "Estimated average CPC (micros): %s%s",
        $metrics->hasAverageCpcMicros()
            ? sprintf("%d", $metrics->getAverageCpcMicros()) : "'none'",
        PHP_EOL
    );
}

/**
 * Creates the campaign to forecast. A campaign to forecast lets you try out various
 * configurations and keywords to find the best optimization for your future campaigns. Once
 * you've found the best campaign configuration, create a serving campaign in your Google Ads
 * account with similar values and keywords. For more details, see:
 *
 * https://support.google.com/google-ads/answer/3022575
 *
 * @return CampaignToForecast the created campaign to forecast
 */
private static function createCampaignToForecast(): CampaignToForecast
{
    // Creates a campaign to forecast.
    $campaignToForecast = new CampaignToForecast([
        'keyword_plan_network' => KeywordPlanNetwork::GOOGLE_SEARCH,
        'bidding_strategy' => new CampaignBiddingStrategy([
            'manual_cpc_bidding_strategy' => new ManualCpcBiddingStrategy([
                'max_cpc_bid_micros' => 1_000_000
            ])
        ]),
        // See https://developers.google.com/google-ads/api/reference/data/geotargets for the
        // list of geo target IDs.
        'geo_modifiers' => [
            new CriterionBidModifier([
                // Geo target constant 2840 is for USA.
                'geo_target_constant' => ResourceNames::forGeoTargetConstant(2840)
            ])
        ],
        // See
        // https://developers.google.com/google-ads/api/reference/data/codes-formats#languages
        // for the list of language criteria IDs. Language constant 1000 is for English.
        'language_constants' => [ResourceNames::forLanguageConstant(1000)],
    ]);

    // Creates forecast ad group based on themes such as creative relevance, product category,
    // or cost per click.
    $forecastAdGroup = new ForecastAdGroup([
        'biddable_keywords' => [
            new BiddableKeyword([
                'max_cpc_bid_micros' => 2_500_000,
                'keyword' => new KeywordInfo([
                    'text' => 'mars cruise',
                    'match_type' => KeywordMatchType::BROAD
                ])
            ]),
            new BiddableKeyword([
                'max_cpc_bid_micros' => 1_500_000,
                'keyword' => new KeywordInfo([
                    'text' => 'cheap cruise',
                    'match_type' => KeywordMatchType::PHRASE
                ])
            ]),
            new BiddableKeyword([
                'max_cpc_bid_micros' => 1_990_000,
                'keyword' => new KeywordInfo([
                    'text' => 'jupiter cruise',
                    'match_type' => KeywordMatchType::BROAD
                ])
            ])
        ],
        'negative_keywords' => [
            new KeywordInfo([
                'text' => 'moon walk',
                'match_type' => KeywordMatchType::BROAD
            ])
        ]
    ]);
    $campaignToForecast->setAdGroups([$forecastAdGroup]);

    return $campaignToForecast;
}
      
```

### Python

```python
def main(client: GoogleAdsClient, customer_id: str):
    """The main method that creates all necessary entities for the example.

    Args:
        client: an initialized GoogleAdsClient instance.
        customer_id: a client customer ID.
    """
    campaign_to_forecast: CampaignToForecast = create_campaign_to_forecast(
        client
    )
    generate_forecast_metrics(client, customer_id, campaign_to_forecast)


def create_campaign_to_forecast(client: GoogleAdsClient) -> CampaignToForecast:
    """Creates the campaign to forecast.

    A campaign to forecast lets you try out various configurations and keywords
    to find the best optimization for your future campaigns. Once you've found
    the best campaign configuration, create a serving campaign in your Google
    Ads account with similar values and keywords. For more details, see:
    https://support.google.com/google-ads/answer/3022575

    Args:
        client: an initialized GoogleAdsClient instance.

    Returns:
        An CampaignToForecast instance.
    """
    googleads_service: GoogleAdsServiceClient = client.get_service(
        "GoogleAdsService"
    )
    # Create a campaign to forecast.
    campaign_to_forecast: CampaignToForecast = client.get_type(
        "CampaignToForecast"
    )
    # Set the bidding strategy.
    campaign_to_forecast.bidding_strategy.manual_cpc_bidding_strategy.max_cpc_bid_micros = (
        1000000
    )

    # For the list of geo target IDs, see:
    # https://developers.google.com/google-ads/api/reference/data/geotargets
    # Geo target constant 2840 is for USA.
    campaign_to_forecast.geo_target_constants.append(
        googleads_service.geo_target_constant_path("2840")
    )

    # For the list of language criteria IDs, see:
    # https://developers.google.com/google-ads/api/reference/data/codes-formats#languages
    # Language criteria 1000 is for English.
    campaign_to_forecast.language_constants.append(
        googleads_service.language_constant_path("1000")
    )

    # Create forecast ad groups based on themes such as creative relevance,
    # product category, or cost per click.
    forecast_ad_group: ForecastAdGroup = client.get_type("ForecastAdGroup")

    # Create and configure three KeywordInfo instances.
    keyword_1: KeywordInfo = client.get_type("KeywordInfo")
    keyword_1.text = "mars cruise"
    keyword_1.match_type = client.enums.KeywordMatchTypeEnum.BROAD

    keyword_2: KeywordInfo = client.get_type("KeywordInfo")
    keyword_2.text = "cheap cruise"
    keyword_2.match_type = client.enums.KeywordMatchTypeEnum.PHRASE

    keyword_3: KeywordInfo = client.get_type("KeywordInfo")
    keyword_3.text = "cheap cruise"
    keyword_3.match_type = client.enums.KeywordMatchTypeEnum.EXACT

    # Add the keywords to the forecast ad group.
    forecast_ad_group.keywords.extend([keyword_1, keyword_2, keyword_3])

    campaign_to_forecast.ad_groups.append(forecast_ad_group)

    return campaign_to_forecast


def generate_forecast_metrics(
    client: GoogleAdsClient,
    customer_id: str,
    campaign_to_forecast: CampaignToForecast,
):
    """Generates forecast metrics and prints the results.

    Args:
        client: an initialized GoogleAdsClient instance.
        customer_id: a client customer ID.
        campaign_to_forecast: a CampaignToForecast to generate metrics for.
    """
    keyword_plan_idea_service: KeywordPlanIdeaServiceClient = (
        client.get_service("KeywordPlanIdeaService")
    )
    request: GenerateKeywordForecastMetricsRequest = client.get_type(
        "GenerateKeywordForecastMetricsRequest"
    )
    request.customer_id = customer_id
    request.campaign = campaign_to_forecast
    # Set the forecast range. Repeat forecasts with different horizons to get a
    # holistic picture.
    # Set the forecast start date to tomorrow.
    tomorrow = datetime.now() + timedelta(days=1)
    request.forecast_period.start_date = tomorrow.strftime("%Y-%m-%d")
    # Set the forecast end date to 30 days from today.
    thirty_days_from_now = datetime.now() + timedelta(days=30)
    request.forecast_period.end_date = thirty_days_from_now.strftime("%Y-%m-%d")

    response: GenerateKeywordForecastMetricsResponse = (
        keyword_plan_idea_service.generate_keyword_forecast_metrics(
            request=request
        )
    )

    metrics = response.campaign_forecast_metrics
    print(f"Estimated daily clicks: {metrics.clicks}")
    print(f"Estimated daily average CPC: {metrics.average_cpc_micros}")
      
```

### Ruby

```ruby
def generate_forecast_metrics(customer_id)
  # GoogleAdsClient will read a config file from
  # ENV['HOME']/google_ads_config.rb when called without parameters
  client = Google::Ads::GoogleAds::GoogleAdsClient.new

  campaign_to_forecast = create_campaign_to_forecast(client)

  # Generates forecast metrics and prints the results.
  keyword_plan_idea_service = client.service.keyword_plan_idea

  # Set the forecast range. Repeat forecasts with different horizons to get a
  # holistic picture.

  forecast_period = client.resource.date_range do |p|
    tomorrow = Date.today + 1
    p.start_date = tomorrow.strftime("%Y-%m-%d")

    # Set the forecast end date to 30 days from today.
    thirty_days_from_now = Date.today + 30
    p.end_date = thirty_days_from_now.strftime("%Y-%m-%d")
  end

  response = keyword_plan_idea_service.generate_keyword_forecast_metrics(
    customer_id: customer_id,
    campaign: campaign_to_forecast,
    forecast_period: forecast_period,
  )

  metrics = response.campaign_forecast_metrics
  puts "Estimated daily clicks: #{metrics.clicks}"
  puts "Estimated daily impressions: #{metrics.impressions}"
  puts "Estimated daily average CPC: #{metrics.average_cpc_micros}"
end

def create_campaign_to_forecast(client)
    campaign_to_forecast = client.resource.campaign_to_forecast do |c|
        c.keyword_plan_network = :GOOGLE_SEARCH

        c.bidding_strategy = client.resource.campaign_bidding_strategy do |bs|
            bs.manual_cpc_bidding_strategy = client.resource.manual_cpc_bidding_strategy do |mbs|
                mbs.max_cpc_bid_micros = 1000000
            end
        end

        criterion_bid_modifier = client.resource.criterion_bid_modifier

        # For the list of geo target IDs, see:
        # https://developers.google.com/google-ads/api/reference/data/geotargets
        # Geo target constant 2840 is for USA.
        criterion_bid_modifier.geo_target_constant = client.path.geo_target_constant("2840")

        c.geo_modifiers << criterion_bid_modifier

        # For the list of language criteria IDs, see:
        # https://developers.google.com/google-ads/api/reference/data/codes-formats#languages
        # Language criteria 1000 is for English.
        language_constant = client.path.language_constant("1000")  # English
        c.language_constants << language_constant

        # Create forecast ad groups based on themes such as creative relevance,
        # product category, or cost per click.
        forecast_ad_group = client.resource.forecast_ad_group

        biddable_keyword_1 = client.resource.biddable_keyword do |bk|
            bk.max_cpc_bid_micros = 1500000
            bk.keyword = client.resource.keyword_info do |k|
                k.text = "mars cruise"
                k.match_type = :BROAD
              end
        end

        biddable_keyword_2 = client.resource.biddable_keyword do |bk|
            bk.max_cpc_bid_micros = 2500000
            bk.keyword = client.resource.keyword_info do |k|
                k.text = "cheap cruise"
                k.match_type = :PHRASE
              end
        end

        biddable_keyword_3 = client.resource.biddable_keyword do |bk|
            bk.max_cpc_bid_micros = 1990000
            bk.keyword = client.resource.keyword_info do |k|
                k.text = "cheap cruise"
                k.match_type = :EXACT
              end
        end

        forecast_ad_group.biddable_keywords << biddable_keyword_1
        forecast_ad_group.biddable_keywords << biddable_keyword_2
        forecast_ad_group.biddable_keywords << biddable_keyword_3

        # Create and configure a negative keyword, then add it to the forecast ad
        # group.
        negative_keyword = client.resource.keyword_info do |k|
            k.text = "moon walk"
            k.match_type = :BROAD
          end
        forecast_ad_group.negative_keywords << negative_keyword

        c.ad_groups << forecast_ad_group
    end

    return campaign_to_forecast
end
      
```

### Perl

```perl
sub generate_forecast_metrics {
  my ($api_client, $customer_id) = @_;

  my $campaign_to_forecast = create_campaign_to_forecast();

  my $keyword_forecast_metrics_response =
    $api_client->KeywordPlanIdeaService()->generate_keyword_forecast_metrics({
      customerId => $customer_id,
      campaign   => $campaign_to_forecast,
      # Set the forecast range. Repeat forecasts with different horizons
      # to get a holistic picture.
      forecastPeriod => Google::Ads::GoogleAds::V26::Common::DateRange->new({
          # Set the forecast start date to tomorrow.
          startDate => strftime("%Y-%m-%d", localtime(time + 60 * 60 * 24)),
          # Set the forecast end date to 30 days from today.
          endDate => strftime("%Y-%m-%d", localtime(time + 60 * 60 * 24 * 30))})
    });

  my $metrics = $keyword_forecast_metrics_response->{campaignForecastMetrics};

  printf "Estimated daily clicks: %s.\n",
    defined $metrics->{clicks} ? $metrics->{clicks} : "undef";
  printf "Estimated average cpc (micros): %s.\n\n",
    defined $metrics->{averageCpcMicros}
    ? $metrics->{averageCpcMicros}
    : "undef";

  return 1;
}

# Creates the campaign to forecast. A campaign to forecast lets you try out
# various configuration and keywords to find the best optimization for your
# future campaigns. Once you've found the best campaign configuration,
# create a serving campaign in your Google Ads account with similar values
# and keywords. For more details, see:
# https://support.google.com/google-ads/answer/3022575
sub create_campaign_to_forecast {
  my ($api_client) = @_;

  # Create a campaign to forecast.
  my $campaign_to_forecast =
    Google::Ads::GoogleAds::V26::Services::KeywordPlanIdeaService::CampaignToForecast
    ->new();

  # Set the bidding strategy.
  $campaign_to_forecast->{biddingStrategy}->{manualCpcBiddingStrategy} =
    Google::Ads::GoogleAds::V26::Services::KeywordPlanIdeaService::ManualCpcBiddingStrategy
    ->new({maxCpcBidMicros => 1000000});

  # See https://developers.google.com/google-ads/api/reference/data/geotargets
  # for the list of geo target IDs.
  # Geo target constant 2840 is for USA.
  $campaign_to_forecast->{geoTargetConstants} = [
    Google::Ads::GoogleAds::V26::Utils::ResourceNames::geo_target_constant(
      2840)];

  # See https://developers.google.com/google-ads/api/reference/data/codes-formats#languages
  # for the list of language criteria IDs.
  $campaign_to_forecast->{languageConstants} = [
    # Language criteria 1000 is for English.
    Google::Ads::GoogleAds::V26::Utils::ResourceNames::language_constant(1000)];

  # Create forecast ad groups based on themes such as creative relevance,
  # product category, or cost per click.
  $campaign_to_forecast->{adGroups} = [
    Google::Ads::GoogleAds::V26::Services::KeywordPlanIdeaService::ForecastAdGroup
      ->new({
        keywords => [
          Google::Ads::GoogleAds::V26::Common::KeywordInfo->new({
              text      => "mars cruise",
              matchType => 'BROAD'
            }
          ),
          Google::Ads::GoogleAds::V26::Common::KeywordInfo->new({
              text      => "cheap cruise",
              matchType => 'PHRASE'
            }
          ),
          Google::Ads::GoogleAds::V26::Common::KeywordInfo->new({
              text      => "jupiter cruise",
              matchType => 'EXACT'
            })]})];

  return $campaign_to_forecast;
}
      
```

### curl

> [!NOTE]
> **Note:** While a direct REST code sample for this step isn't provided here, you can achieve this using a manual REST request.   
>
> Refer to the Google Ads API REST interface documentation and the method-specific reference pages. You will need to construct the JSON payload based on the proto definitions.   
>
> Key Resources:
>
> - [Using REST](https://developers.google.com/google-ads/api/rest/overview.md.txt)
> - [REST Interface Structure](https://developers.google.com/google-ads/api/rest/design/overview.md.txt)
> - [JSON Field Mappings](https://developers.google.com/google-ads/api/rest/design/json-mappings.md.txt)
> - Consult the [REST API Reference](https://developers.google.com/google-ads/api/reference/rpc/latest/overview) for the specific service and method.

<br />

## Map to the UI

The following table maps
[`KeywordPlanIdeaService.GenerateKeywordForecastMetrics`](https://developers.google.com/google-ads/api/reference/rpc/v26/KeywordPlanIdeaService/GenerateKeywordForecastMetrics.md.txt)
parameters to Keyword Planner in the Google Ads UI:

| Keyword Planner in the UI | Google Ads API |
|---|---|
| Enter Keywords | - **v24 and later:** [`ForecastAdGroup.keywords`](https://developers.google.com/google-ads/api/reference/rpc/v26/ForecastAdGroup.md.txt#keywords[]) - **v23 and earlier:** [`ForecastAdGroup.biddable_keywords`](https://developers.google.com/google-ads/api/reference/rpc/v23/ForecastAdGroup.md.txt#biddable_keywords[]) |
| [Locations](https://developers.google.com/google-ads/api/data/geotargets.md.txt) | - **v24 and later:** [`CampaignToForecast.geo_target_constants`](https://developers.google.com/google-ads/api/reference/rpc/v26/CampaignToForecast.md.txt#geo_target_constants[]) - **v23 and earlier:** [`CampaignToForecast.geo_modifiers`](https://developers.google.com/google-ads/api/reference/rpc/v23/CampaignToForecast.md.txt#geo_modifiers[]) |
| [Languages](https://developers.google.com/google-ads/api/data/codes-formats.md.txt#languages) | [`CampaignToForecast.language_constants`](https://developers.google.com/google-ads/api/reference/rpc/v26/CampaignToForecast.md.txt#language_constants[]) |
| Daily Budget | - [`ManualCpcBiddingStrategy.daily_budget_micros`](https://developers.google.com/google-ads/api/reference/rpc/v26/ManualCpcBiddingStrategy.md.txt#daily_budget_micros) - [`MaximizeClicksBiddingStrategy.daily_target_spend_micros`](https://developers.google.com/google-ads/api/reference/rpc/v26/MaximizeClicksBiddingStrategy.md.txt#daily_target_spend_micros) - [`MaximizeConversionsBiddingStrategy.daily_target_spend_micros`](https://developers.google.com/google-ads/api/reference/rpc/v26/MaximizeConversionsBiddingStrategy.md.txt#daily_target_spend_micros) |
| CPC Bid | - [`CampaignToForecast.bidding_strategy`](https://developers.google.com/google-ads/api/reference/rpc/v26/CampaignToForecast.md.txt#bidding_strategy) - [`ManualCpcBiddingStrategy.max_cpc_bid_micros`](https://developers.google.com/google-ads/api/reference/rpc/v26/ManualCpcBiddingStrategy.md.txt#max_cpc_bid_micros) - [`MaximizeClicksBiddingStrategy.max_cpc_bid_ceiling_micros`](https://developers.google.com/google-ads/api/reference/rpc/v26/MaximizeClicksBiddingStrategy.md.txt#max_cpc_bid_ceiling_micros) - **v23 and earlier:** [`ForecastAdGroup.max_cpc_bid_micros`](https://developers.google.com/google-ads/api/reference/rpc/v23/ForecastAdGroup.md.txt#max_cpc_bid_micros), [`BiddableKeyword.max_cpc_bid_micros`](https://developers.google.com/google-ads/api/reference/rpc/v23/BiddableKeyword.md.txt#max_cpc_bid_micros) |
| Date Range | [`GenerateKeywordForecastMetricsRequest.forecast_period`](https://developers.google.com/google-ads/api/reference/rpc/v26/GenerateKeywordForecastMetricsRequest.md.txt#forecast_period) |