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)

Manual mix

If you are already familiar with Google's video ad formats, the listPlannableProducts method on ReachPlanService will show the available formats for a given location ID.

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)

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)