Generate a Reach Curve

Important: This feature is available to allowlisted accounts only. Contact your Google representative if you need access to the feature.

Once you have gathered the targeting settings and a product mix for your media plan, you can generate a curve of budgets versus potential reach using the GenerateReachForecast method in ReachPlanService. See the glossary and media plan guide for details on the request fields.

Caution: You can save individual curves to provide convenience for your users. Caching curves en masse is strictly prohibited. If you need to generate curves en masse, check with your Google representative.

The curve includes impression and user reach in absolute numbers, as well as universe sizes corresponding to the census population and YouTube audience size for the requested demographic and country.

C#

public void GetReachCurve(ReachPlanServiceClient reachPlanService,
    GenerateReachForecastRequest request)
{
    GenerateReachForecastResponse response = reachPlanService.GenerateReachForecast(
        request);
    Console.WriteLine("Reach curve output:");
    Console.WriteLine(
        "Currency, Cost Micros, On-Target Reach, On-Target Impressions, Total Reach," +
        " Total Impressions, Products");
    foreach (ReachForecast point in response.ReachCurve.ReachForecasts)
    {
        Console.Write($"{request.CurrencyCode}, ");
        Console.Write($"{point.CostMicros}, ");
        Console.Write($"{point.Forecast.OnTargetReach}, ");
        Console.Write($"{point.Forecast.OnTargetImpressions}, ");
        Console.Write($"{point.Forecast.TotalReach}, ");
        Console.Write($"{point.Forecast.TotalImpressions}, ");
        Console.Write("\"[");
        foreach (PlannedProductReachForecast productReachForecast in
            point.PlannedProductReachForecasts)
        {
            Console.Write($"(Product: {productReachForecast.PlannableProductCode}, ");
            Console.Write($"Budget Micros: {productReachForecast.CostMicros}), ");
        }

        Console.WriteLine("]\"");
    }
}
ForecastReach.cs

PHP

private static function getReachCurve(
    GoogleAdsClient $googleAdsClient,
    int $customerId,
    array $productMix,
    string $locationId,
    string $currencyCode
) {
    // Valid durations are between 1 and 90 days.
    $duration = new CampaignDuration(['duration_in_days' => 28]);
    $targeting = new Targeting([
        'plannable_location_id' => $locationId,
        'age_range' => ReachPlanAgeRange::AGE_RANGE_18_65_UP,
        'genders' => [
            new GenderInfo(['type' => GenderType::FEMALE]),
            new GenderInfo(['type' => GenderType::MALE])
        ],
        'devices' => [
            new DeviceInfo(['type' => Device::DESKTOP]),
            new DeviceInfo(['type' => Device::MOBILE]),
            new DeviceInfo(['type' => Device::TABLET])
        ]
    ]);

    // See the docs for defaults and valid ranges:
    // https://developers.google.com/google-ads/api/reference/rpc/latest/GenerateReachForecastRequest
    $response = $googleAdsClient->getReachPlanServiceClient()->generateReachForecast(
        $customerId,
        $duration,
        $productMix,
        ['currencyCode' => $currencyCode, 'targeting' => $targeting]
    );

    printf(
        "Reach curve output:%sCurrency, Cost Micros, On-Target Reach, On-Target Imprs," .
            " Total Reach, Total Imprs, Products%s",
        PHP_EOL,
        PHP_EOL
    );
    foreach ($response->getReachCurve()->getReachForecasts() as $point) {
        $products = '';
        /** @var ReachForecast $point */
        foreach ($point->getPlannedProductReachForecasts() as $plannedProductReachForecast) {
            /** @var PlannedProductReachForecast $plannedProductReachForecast */
            $products .= sprintf(
                '(Product: %s, Budget Micros: %s)',
                $plannedProductReachForecast->getPlannableProductCode(),
                $plannedProductReachForecast->getCostMicros()
            );
        }
        printf(
            "%s, %d, %d, %d, %d, %d, %s%s",
            $currencyCode,
            $point->getCostMicros(),
            $point->getForecast()->getOnTargetReach(),
            $point->getForecast()->getOnTargetImpressions(),
            $point->getForecast()->getTotalReach(),
            $point->getForecast()->getTotalImpressions(),
            $products,
            PHP_EOL
        );
    }
}
ForecastReach.php

Python

def _request_reach_curve(
    client, customer_id, product_mix, location_id, currency_code
):
    """Creates a sample request for a given product mix.

    Args:
      client: A google.ads.google_ads.client.GoogleAdsClient instance.
      customer_id: The customer ID for the reach forecast.
      product_mix: The product mix for the reach forecast.
      location_id: Location ID to plan for. You can get a valid loction ID from
        https://developers.google.com/adwords/api/docs/appendix/geotargeting or
        by calling ListPlannableLocations on the ReachPlanService.
      currency_code: Three-character ISO 4217 currency code.
    """
    reach_request = client.get_type(
        "GenerateReachForecastRequest", version="v6"
    )

    reach_request.customer_id = customer_id

    # Valid durations are between 1 and 90 days.
    campaign_duration = reach_request.campaign_duration
    campaign_duration.duration_in_days = 28

    targeting = reach_request.targeting
    targeting.plannable_location_id = location_id
    targeting.age_range = client.get_type(
        "ReachPlanAgeRangeEnum", version="v6"
    ).AGE_RANGE_18_65_UP

    genders = targeting.genders
    gender_types = [
        client.get_type("GenderTypeEnum", version="v6").FEMALE,
        client.get_type("GenderTypeEnum", version="v6").MALE,
    ]
    for gender_type in gender_types:
        gender = client.get_type("GenderInfo", version="v6")
        gender.type = gender_type
        genders.append(gender)

    devices = targeting.devices
    device_types = [
        client.get_type("DeviceEnum", version="v6").DESKTOP,
        client.get_type("DeviceEnum", version="v6").MOBILE,
        client.get_type("DeviceEnum", version="v6").TABLET,
    ]
    for device_type in device_types:
        device = client.get_type("DeviceInfo", version="v6")
        device.type = device_type
        devices.append(device)

    reach_plan_service = client.get_service("ReachPlanService", version="v6")

    # See the docs for defaults and valid ranges:
    # https://developers.google.com/google-ads/api/reference/rpc/latest/GenerateReachForecastRequest
    response = reach_plan_service.generate_reach_forecast(
        customer_id,
        campaign_duration,
        product_mix,
        currency_code=currency_code,
        cookie_frequency_cap=0,
        min_effective_frequency=1,
        targeting=targeting,
    )

    print(
        "Currency, Cost, On-Target Reach, On-Target Imprs, Total Reach, "
        " Total Imprs, Products"
    )
    for point in response.reach_curve.reach_forecasts:
        print(
            [
                currency_code,
                point.cost_micros / ONE_MILLION,
                point.forecast.on_target_reach,
                point.forecast.on_target_impressions,
                point.forecast.total_reach,
                point.forecast.total_impressions,
                [
                    {p.plannable_product_code: p.cost_micros / ONE_MILLION}
                    for p in point.planned_product_reach_forecasts
                ],
            ]
        )
forecast_reach.py

Perl

sub pull_reach_curve {
  my ($reach_plan_service, $reach_request) = @_;

  my $response = $reach_plan_service->generate_reach_forecast($reach_request);
  print "Reach curve output:\n";
  print "Currency,\tCost Micros,\tOn-Target Reach,\tOn-Target Imprs,\t" .
    "Total Reach,\tTotal Imprs,\tProducts\n";
  foreach my $point (@{$response->{reachCurve}{reachForecasts}}) {
    printf "%s,\t%d,\t%d,\t%d,\t%d,\t%d,\t'[", $reach_request->{currencyCode},
      $point->{costMicros}, $point->{forecast}{onTargetReach},
      $point->{forecast}{onTargetImpressions}, $point->{forecast}{totalReach},
      $point->{forecast}{totalImpressions};
    foreach my $productReachForecast (@{$point->{plannedProductReachForecasts}})
    {
      printf "(Product: %s, Budget Micros: %d), ",
        $productReachForecast->{plannableProductCode},
        $productReachForecast->{costMicros};
    }
    print "]'\n";
  }
}
forecast_reach.pl