Google Ads API is returning to beta status. Please read our blog post for more details.

Specifying a Media Plan

Google offers a variety of products and audiences you can use to build campaigns, but you may not know the exact formulation when creating a plan. To help with this, ReachPlanService provides discovery methods you can use to generate a curve.

Audience targeting

The first component of a media plan is audience targeting, which includes:

Locations
Use the listPlannableLocations method to find supported location IDs.
Age Ranges
Reference the ReachPlanAgeRange enum.
Genders
Reference the GenderInfo criterion.
Devices
Reference the DeviceInfo criterion.

Product mix

In addition to the targeting information, you must specify a product mix in order to generate a curve. There are two ways to do this.

Suggested mix

If you are not familiar with Google's video ad formats, then you can use the generateProductMixIdeas method to get a recommended split for a given budget and preferences. The available preferences you can specify currently include:

  • Whether or not you would like a guaranteed price on inventory.
  • If you would like video ad formats that include sound, are skippable or only show on top content.
  • A ReachPlanAdLength.
Python
def forecast_suggested_mix(
    client, customer_id, location_id, currency_code, budget):
    """Pulls a forecast for a product mix based on your set of preferences.

    Args:
      client: A google.ads.google_ads.client.GoogleAdsClient instance.
      customer_id: The customer ID 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.
      budget: Budget to allocate to the plan.
    """
    preferences = client.get_type('Preferences', version='v2')
    preferences.has_guaranteed_price.value = True
    preferences.starts_with_sound.value = True
    preferences.is_skippable.value = False
    preferences.top_content_only.value = True
    preferences.ad_length = client.get_type(
            'ReachPlanAdLengthEnum', version='v2').FIFTEEN_OR_TWENTY_SECONDS

    reach_plan_service = client.get_service('ReachPlanService', version='v2')
    mix_response = reach_plan_service.generate_product_mix_ideas(
            customer_id=customer_id,
            plannable_location_id=_string_value(client, location_id),
            preferences=preferences,
            currency_code=_string_value(client, currency_code),
            budget_micros=_int_64_value(client, budget * ONE_MILLION))

    product_mix = []
    for product in mix_response.product_allocation:
        planned_product = client.get_type('PlannedProduct', version='v2')
        planned_product.plannable_product_code.value = (
                product.plannable_product_code.value)
        planned_product.budget_micros.value = product.budget_micros.value
        product_mix.append(planned_product)

    _request_reach_curve(
            client, customer_id, product_mix, location_id, currency_code)
C#
public void ForecastSuggestedMix(
    ReachPlanServiceClient reachPlanService,
    string customerId,
    string locationId,
    string currencyCode,
    long budgetMicros)
{
    // Note: If preferences are too restrictive, then the response will be empty.
    Preferences preferences = new Preferences()
    {
        HasGuaranteedPrice = true,
        StartsWithSound = true,
        IsSkippable = false,
        TopContentOnly = true,
        AdLength = ReachPlanAdLength.FifteenOrTwentySeconds
    };

    GenerateProductMixIdeasRequest mixRequest = new GenerateProductMixIdeasRequest()
    {
        BudgetMicros = Convert.ToInt64((double)budgetMicros),
        CurrencyCode = currencyCode,
        CustomerId = customerId,
        PlannableLocationId = locationId,
        Preferences = preferences
    };

    GenerateProductMixIdeasResponse mixResponse =
        reachPlanService.GenerateProductMixIdeas(mixRequest);

    List<PlannedProduct> productMix = new List<PlannedProduct>();

    foreach (ProductAllocation product in mixResponse.ProductAllocation)
    {
        productMix.Add(
            new PlannedProduct()
            {
                PlannableProductCode = product.PlannableProductCode,
                BudgetMicros = product.BudgetMicros
            });
    }

    GenerateReachForecastRequest curveRequest =
        BuildReachRequest(customerId, productMix, locationId, currencyCode);

    PullReachCurve(reachPlanService, curveRequest);
}

Manual mix

If you are already familiar with Google's video ad formats, the listPlannableProducts method on ReachPlanService will show the latest available formats for a given location ID. Please keep in mind that these values change periodically, so it is best to provide your users with live results rather than persisting responses offline.

Python
def show_plannable_products(client, location_id):
    """Lists plannable products for a given location.

    Args:
      client: A google.ads.google_ads.client.GoogleAdsClient instance.
      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.
    """
    reach_plan_service = client.get_service('ReachPlanService', version='v2')
    response = reach_plan_service.list_plannable_products(
            plannable_location_id=_string_value(client, location_id))
    print('Plannable Products for Location ID {}'.format(location_id))
    print(response)
C#
public void ShowPlannableProducts(
    ReachPlanServiceClient reachPlanService, string locationId)
{
    ListPlannableProductsRequest request = new ListPlannableProductsRequest()
    {
        PlannableLocationId = locationId
    };
    ListPlannableProductsResponse response = reachPlanService.ListPlannableProducts(
        request);

    Console.WriteLine($"Plannable Products for location {locationId}:");
    foreach (ProductMetadata product in response.ProductMetadata)
    {
        Console.WriteLine($"{product.PlannableProductCode}:");
        Console.WriteLine("Age Ranges:");
        foreach (var ageRange in product.PlannableTargeting.AgeRanges)
        {
            Console.WriteLine($"\t- {ageRange}");
        }
        Console.WriteLine("Genders:");
        foreach (var gender in product.PlannableTargeting.Genders)
        {
            Console.WriteLine($"\t- {gender.Type}");
        }
        Console.WriteLine("Devices:");
        foreach (var device in product.PlannableTargeting.Devices)
        {
            Console.WriteLine($"\t- {device.Type}");
        }
    }
}

To generate a curve you would simply assign a desired budget to each product.

Python
def forecast_manual_mix(
        client, customer_id, location_id, currency_code, budget):
    """Pulls a forecast for product mix created manually.

    Args:
      client: A google.ads.google_ads.client.GoogleAdsClient instance.
      customer_id: The customer ID 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.
      budget: Budget to allocate to the plan.
    """
    product_mix = []
    trueview_allocation = 0.15
    bumper_allocation = 1 - trueview_allocation
    product_splits = [
        ('TRUEVIEW_IN_STREAM', trueview_allocation),
        ('BUMPER', bumper_allocation),
    ]
    for product, split in product_splits:
        planned_product = client.get_type('PlannedProduct', version='v2')
        planned_product.plannable_product_code.value = product
        planned_product.budget_micros.value = math.trunc(
            budget * ONE_MILLION * split)
        product_mix.append(planned_product)

    _request_reach_curve(
            client, customer_id, product_mix, location_id, currency_code)
C#
public void ForecastManualMix(
                ReachPlanServiceClient reachPlanService,
                string customerId,
                string locationId,
                string currencyCode,
                long budgetMicros)
{
    List<PlannedProduct> productMix = new List<PlannedProduct>();

    // Set up a ratio to split the budget between two products.
    double trueviewAllocation = 0.15;
    double bumperAllocation = 1 - trueviewAllocation;

    // See listPlannableProducts on ReachPlanService to retrieve a list
    // of valid PlannableProductCode's for a given location:
    // https://developers.google.com/google-ads/api/reference/rpc/google.ads.googleads.v2.services#reachplanservice
    productMix.Add(new PlannedProduct()
    {
        PlannableProductCode = "TRUEVIEW_IN_STREAM",
        BudgetMicros = Convert.ToInt64((double)budgetMicros * trueviewAllocation)
    });
    productMix.Add(new PlannedProduct()
    {
        PlannableProductCode = "BUMPER",
        BudgetMicros = Convert.ToInt64((double)budgetMicros * bumperAllocation)
    });

    GenerateReachForecastRequest request =
        BuildReachRequest(customerId, productMix, locationId, currencyCode);

    PullReachCurve(reachPlanService, request);
}