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, please 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 (ProductAllocation product in point.ForecastedProductAllocations)
        {
            Console.Write($"(Product: {product.PlannableProductCode}, ");
            Console.Write($"Budget Micros: {product.BudgetMicros}), ");
        }

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

PHP

private static function getReachCurve(
    GoogleAdsClient $googleAdsClient,
    int $customerId,
    array $productMix,
    string $locationId,
    string $currencyCode
) {
    $duration = new CampaignDuration([
        // Valid durations are between 1 and 90 days.
        'duration_in_days' => new Int32Value(['value' => 28])
    ]);

    $targeting = new Targeting([
        'plannable_location_id' => new StringValue(['value' => $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' => new StringValue(['value' => $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->getForecastedProductAllocations() as $product) {
            /** @var ProductAllocation $product */
            $products .= sprintf(
                '(Product: %s, Budget Micros: %s)',
                $product->getPlannableProductCodeUnwrapped(),
                $product->getBudgetMicrosUnwrapped()
            );
        }
        printf(
            "%s, %d, %d, %d, %d, %d, %s%s",
            $currencyCode,
            $point->getCostMicrosUnwrapped(),
            $point->getForecast()->getOnTargetReachUnwrapped(),
            $point->getForecast()->getOnTargetImpressionsUnwrapped(),
            $point->getForecast()->getTotalReachUnwrapped(),
            $point->getForecast()->getTotalImpressionsUnwrapped(),
            $products,
            PHP_EOL
        );
    }
}
ForecastReach.php

Python

def _request_reach_curve(
    client, customer_id, product_mix, location_id, currency_code
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 $product (@{$point->{forecastedProductAllocations}}) {
      printf "(Product: %s, Budget Micros: %d), ",
        $product->{plannableProductCode}, $product->{budgetMicros};
    }
    print "]'\n";
  }
}
forecast_reach.pl