预测

简介

本指南介绍了在 Google Ad Manager API 中使用预测功能的不同方式。

流量预测

借助流量预测,您可以读取历史流量以及未来的展示机会,以便寻找更好的方式来细分和打包广告资源。

Java

// Create the date range. Include the previous and next 7 days.
Interval interval =
    new Interval(
        Instant.now().plus(Duration.standardDays(-7)),
        Instant.now().plus(Duration.standardDays(7)));
DateRange dateRange = new DateRange();
dateRange.setStartDate(DateTimes.toDateTime(interval.getStart()).getDate());
dateRange.setEndDate(DateTimes.toDateTime(interval.getEnd()).getDate());

// Request the traffic data.
TrafficDataRequest trafficDataRequest = new TrafficDataRequest();
trafficDataRequest.setRequestedDateRange(dateRange);
trafficDataRequest.setTargeting(targeting);
TrafficDataResponse trafficData = forecastService.getTrafficData(trafficDataRequest);
    

Python


# Create a start date that's 7 days in the past and an end date that's 7 days
# in the future.
today = datetime.date.today()
start_date = today - datetime.timedelta(days=7)
end_date = today + datetime.timedelta(days=7)

# Create targeting.
targeting = {
    'inventoryTargeting': {
        'targetedAdUnits': [
            {
                'includeDescendants': True,
                'adUnitId': root_ad_unit_id,
            }
        ]
    }
}

# Request the traffic forecast data.
traffic_data = forecast_service.getTrafficData({
    'targeting': targeting,
    'requestedDateRange': {
        'startDate': start_date,
        'endDate': end_date
    }
})
    

PHP


// Create the date range. Include the previous and next 7 days.
$startDate = AdManagerDateTimes::fromDateTime(new DateTime('-7 day'))
    ->getDate();
$endDate = AdManagerDateTimes::fromDateTime(new DateTime('+7 day'))
    ->getDate();
$dateRange = new DateRange();
$dateRange->setStartDate($startDate);
$dateRange->setEndDate($endDate);

// Request the traffic forecast data.
$trafficDataRequest = new TrafficDataRequest();
$trafficDataRequest->setRequestedDateRange($dateRange);
$trafficDataRequest->setTargeting($targeting);
$trafficData = $forecastService->getTrafficData($trafficDataRequest);
    

C#


TrafficDataRequest trafficDataRequest = new TrafficDataRequest() {
    requestedDateRange = new DateRange() {
        startDate =
            DateTimeUtilities.FromDateTime(startDate, "America/New_York").date,
        endDate = DateTimeUtilities.FromDateTime(endDate, "America/New_York").date
    },
    targeting = new Targeting() {
        inventoryTargeting = new InventoryTargeting()
        {
            targetedAdUnits = new AdUnitTargeting[] {
                new AdUnitTargeting() {
                 adUnitId = rootAdUnitId,
                 includeDescendants = true
                }
            }
        }
    }
};
TrafficDataResponse trafficData =
    forecastService.getTrafficData(trafficDataRequest);
    

Ruby


# Create a start date that's 7 days in the past and an end date that's 7 days
# in the future.
today = ad_manager.today
start_date = today - 7
end_date = today + 7

# Create targeting.
targeting = {
  :inventory_targeting => {
    :targeted_ad_units => [
      {
        :include_descendants => true,
        :ad_unit_id => root_ad_unit_id
      }
    ]
  }
}

# Request the traffic forecast data.
traffic_data = forecast_service.get_traffic_data({
  :targeting => targeting,
  :requested_date_range => {
    :start_date => start_date.to_h, :end_date => end_date.to_h
  }
})
    

可用性预测

AvailabilityForecast 会报告可预订订单项的最大可用单元数。这种预测类似于界面中的检查广告资源功能。

预测范围包括可用单元数、匹配的单元数、可能的单元数、已投放的单元数和预留的单元数。它还可以包含所有竞争订单项,以及每个定位条件细分的可用单元数,具体取决于 AvailabilityForecastOptions 中设置的选项。默认情况下,这两种预测均不会纳入预测范围。

定位细分包括每个定位条件的匹配单元数和可用单元数。这些细分条目是根据订单项定位条件自动生成的。例如,定位到广告单元 ID 123456 的订单项将包含类似于以下内容的细分:

<targetingCriteriaBreakdowns>
  <targetingDimension>AD_UNIT</targetingDimension>
  <targetingCriteriaId>123456</targetingCriteriaId>
  <targetingCriteriaName>My Ad Unit Name</targetingCriteriaName>
   <excluded>false</excluded>
   <availableUnits>1000</availableUnits>
   <matchedUnits>2300</matchedUnits>
</targetingCriteriaBreakdowns>

您可以对现有订单项或预测性订单项运行广告资源预测。

现有订单项

您可以使用现有订单项的 ID 为其运行广告资源预测。

Java


  // Get the ForecastService.
  ForecastServiceInterface forecastService =
      adManagerServices.get(session, ForecastServiceInterface.class);

  // Get forecast for line item.
  AvailabilityForecastOptions options = new AvailabilityForecastOptions();
  options.setIncludeContendingLineItems(true);
  options.setIncludeTargetingCriteriaBreakdown(true);
  AvailabilityForecast forecast =
      forecastService.getAvailabilityForecastById(lineItemId, options);

  long matched = forecast.getMatchedUnits();
  double availablePercent = (forecast.getAvailableUnits() / (matched * 1.0)) * 100;
  String unitType = forecast.getUnitType().toString().toLowerCase();

  System.out.printf("%d %s matched.%n", matched, unitType);
  System.out.printf("%.2f%% %s available.%n", availablePercent, unitType);

  if (forecast.getPossibleUnits() != null) {
    double possiblePercent = (forecast.getPossibleUnits() / (matched * 1.0)) * 100;
    System.out.printf("%.2f%% %s possible.%n", possiblePercent, unitType);
  }

  System.out.printf(
      "%d contending line items.%n",
      forecast.getContendingLineItems() == null ? 0 : forecast.getContendingLineItems().length);
    

Python


  # Initialize appropriate service.
  forecast_service = client.GetService('ForecastService', version='v202402')

  # Set forecasting options.
  forecast_options = {
      'includeContendingLineItems': True,
      'includeTargetingCriteriaBreakdown': True,
  }

  # Get forecast for line item.
  forecast = forecast_service.getAvailabilityForecastById(
      line_item_id, forecast_options)
  matched = int(forecast['matchedUnits'])
  available_units = int(forecast['availableUnits'])

  if matched > 0:
    available_percent = (float(available_units) / matched) * 100.
  else:
    available_percent = 0

  contending_line_items = getattr(forecast, 'contentingLineItems', [])

  # Display results.
  print('%s %s matched.' % (matched, forecast['unitType'].lower()))
  print('%s%% %s available.' % (
      available_percent, forecast['unitType'].lower()))
  print('%d contending line items.' % len(contending_line_items))

  if 'possibleUnits' in forecast and matched:
    possible_percent = (int(forecast['possibleUnits'])/float(matched)) * 100.
    print('%s%% %s possible' % (possible_percent, forecast['unitType'].lower()))
    

PHP


      $forecastService = $serviceFactory->createForecastService($session);

      // Get forecast for line item.
      $options = new AvailabilityForecastOptions();
      $options->setIncludeContendingLineItems(true);
      $options->setIncludeTargetingCriteriaBreakdown(true);
      $forecast = $forecastService->getAvailabilityForecastById(
          $lineItemId,
          $options
      );

      // Print out forecast results.
      $matchedUnits = $forecast->getMatchedUnits();
      $unitType = strtolower($forecast->getUnitType());
      printf("%d %s matched.%s", $matchedUnits, $unitType, PHP_EOL);

      if ($matchedUnits > 0) {
          $availableUnits = $forecast->getAvailableUnits();
          $percentAvailableUnits = $availableUnits / $matchedUnits * 100;
          $possibleUnits = $forecast->getPossibleUnits();
          $percentPossibleUnits = $possibleUnits / $matchedUnits * 100;
          printf(
              "%.2d%% %s available.%s",
              $percentAvailableUnits,
              $unitType,
              PHP_EOL
          );
          printf(
              "%.2d%% %s possible.%s",
              $percentPossibleUnits,
              $unitType,
              PHP_EOL
          );
      }

      printf(
          "%d contending line items.%s",
          count($forecast->getContendingLineItems()),
          PHP_EOL
      );
    

C#


using (ForecastService forecastService = user.GetService<ForecastService>())
{
// Get forecast for line item.
AvailabilityForecastOptions options = new AvailabilityForecastOptions();
options.includeContendingLineItems = true;
options.includeTargetingCriteriaBreakdown = true;
AvailabilityForecast forecast =
    forecastService.getAvailabilityForecastById(lineItemId, options);

// Display results.
long matched = forecast.matchedUnits;
double availablePercent =
    (double) (forecast.availableUnits / (matched * 1.0)) * 100;
String unitType = forecast.unitType.ToString().ToLower();

Console.WriteLine("{0} {1} matched.\n{2} % {3} available.", matched, unitType,
    availablePercent, unitType);
if (forecast.possibleUnitsSpecified)
{
    double possiblePercent =
        (double) (forecast.possibleUnits / (matched * 1.0)) * 100;
    Console.WriteLine(possiblePercent + "% " + unitType + " possible.\n");
}

Console.WriteLine("{0} contending line items.",
    (forecast.contendingLineItems != null)
        ? forecast.contendingLineItems.Length
        : 0);
    

Ruby


  # Get the ForecastService.
  forecast_service = ad_manager.service(:ForecastService, API_VERSION)
  # Set forecasting options.
  forecast_options = {
    :include_contending_line_items => True,
    :include_targeting_criteria_breakdown => True,
  }

  # Get forecast for the line item.
  forecast = forecast_service.get_availability_forecast_by_id(
      line_item_id, forecast_options
  )

  unless forecast.nil?
    # Display results.
    matched = forecast[:matched_units]
    available_percent = forecast[:available_units] * 100.0 / matched
    unit_type = forecast[:unit_type].to_s.downcase
    puts '%.2f %s matched.' % [matched, unit_type]
    puts '%.2f%% of %s available.' % [available_percent, unit_type]
    puts '%d contending line items.' % forecast[:contending_line_items].size
    unless forecast[:possible_units].nil?
      possible_percent = forecast[:possible_units] * 100.0 / matched
      puts '%.2f%% of %s possible.' % [possible_percent, unit_type]
    end
  end
    

此示例的输出结果类似于以下内容:

100 clicks matched.
2 contending line items.

预测性订单项

或者,您也可以对预测性订单项进行实例化,然后进行预测,而无需保留该订单项。为此,请实例化一个本地订单项对象,并在 ProspectiveLineItem 上对其进行设置。 如果您设置了广告客户 ID,则预测还会考虑统一屏蔽规则

Java


  // Get forecast for prospective line item.
  ProspectiveLineItem prospectiveLineItem = new ProspectiveLineItem();
  prospectiveLineItem.setAdvertiserId(advertiserId);
  prospectiveLineItem.setLineItem(lineItem);
  AvailabilityForecastOptions options = new AvailabilityForecastOptions();
  options.setIncludeContendingLineItems(true);
  options.setIncludeTargetingCriteriaBreakdown(true);

  AvailabilityForecast forecast =
      forecastService.getAvailabilityForecast(prospectiveLineItem, options);
    

Python


  prospective_line_item = {
      'lineItem': line_item,
      'advertiserId': advertiser_id
  }

  # Set forecasting options.
  forecast_options = {
      'includeContendingLineItems': True,
      # The field includeTargetingCriteriaBreakdown can only be set if
      # breakdowns are not manually specified.
      # 'includeTargetingCriteriaBreakdown': True,
      'breakdown': {
          'timeWindows': [
              now_datetime,
              now_datetime + datetime.timedelta(days=1),
              now_datetime + datetime.timedelta(days=2),
              now_datetime + datetime.timedelta(days=3),
              now_datetime + datetime.timedelta(days=4),
              end_datetime
          ],
          'targets': [
              {
                  # Optional, the name field is only used to identify this
                  # breakdown in the response.
                  'name': 'United States',
                  'targeting': {
                      'inventoryTargeting': {
                          'targetedAdUnits': [
                              {
                                  'includeDescendants': True,
                                  'adUnitId': root_ad_unit_id,
                              }
                          ]
                      },
                      'geoTargeting': {
                          'targetedLocations': [
                              {
                                  'id': '2840',
                                  'displayName': 'US'
                              }
                          ]
                      }
                  }
              },
              {
                  # Optional, the name field is only used to identify this
                  # breakdown in the response.
                  'name': 'Geneva',
                  'targeting': {
                      'inventoryTargeting': {
                          'targetedAdUnits': [
                              {
                                  'includeDescendants': True,
                                  'adUnitId': root_ad_unit_id,
                              }
                          ]
                      },
                      'geoTargeting': {
                          'targetedLocations': [
                              {
                                  'id': '20133',
                                  'displayName': 'Geneva'
                              }
                          ]
                      }
                  }
              }
          ]
      }
  }

  # Get forecast.
  forecast = forecast_service.getAvailabilityForecast(
      prospective_line_item, forecast_options)
    

PHP


      // Get forecast for prospective line item.
      $prospectiveLineItem = new ProspectiveLineItem();
      $prospectiveLineItem->setAdvertiserId($advertiserId);
      $prospectiveLineItem->setLineItem($lineItem);
      $options = new AvailabilityForecastOptions();
      $options->setIncludeContendingLineItems(true);
      $options->setIncludeTargetingCriteriaBreakdown(true);

      $forecast = $forecastService->getAvailabilityForecast(
          $prospectiveLineItem,
          $options
      );
    

C#


// Get availability forecast.
AvailabilityForecastOptions options = new AvailabilityForecastOptions()
{
    includeContendingLineItems = true,
    // Targeting criteria breakdown can only be included if breakdowns
    // are not speficied.
    includeTargetingCriteriaBreakdown = false,
    breakdown = new ForecastBreakdownOptions
    {
        timeWindows = new DateTime[] {
            lineItem.startDateTime,
            DateTimeUtilities.FromDateTime(tomorrow.AddDays(1),
                "America/New_York"),
            DateTimeUtilities.FromDateTime(tomorrow.AddDays(2),
                "America/New_York"),
            DateTimeUtilities.FromDateTime(tomorrow.AddDays(3),
                "America/New_York"),
            DateTimeUtilities.FromDateTime(tomorrow.AddDays(4),
                "America/New_York"),
            lineItem.endDateTime
        },
        targets = new ForecastBreakdownTarget[] {
            new ForecastBreakdownTarget()
            {
                // Optional name field to identify this breakdown
                // in the response.
                name = "United States",
                targeting = new Targeting()
                {
                    inventoryTargeting = new InventoryTargeting()
                    {
                        targetedAdUnits = new AdUnitTargeting[] {
                            new AdUnitTargeting()
                            {
                                adUnitId = rootAdUnitId,
                                includeDescendants = true
                            }
                        }
                    },
                    geoTargeting = new GeoTargeting()
                    {
                        targetedLocations = new Location[] {
                            new Location() { id = 2840L }
                        }
                    }
                }
            }, new ForecastBreakdownTarget()
            {
                // Optional name field to identify this breakdown
                // in the response.
                name = "Geneva",
                targeting = new Targeting()
                {
                    inventoryTargeting = new InventoryTargeting()
                    {
                        targetedAdUnits = new AdUnitTargeting[] {
                            new AdUnitTargeting()
                            {
                                adUnitId = rootAdUnitId,
                                includeDescendants = true
                            }
                        }
                    },
                    geoTargeting = new GeoTargeting()
                    {
                        targetedLocations = new Location[] {
                            new Location () { id = 20133L }
                        }
                    }
                }
            }
        }
    }
};
ProspectiveLineItem prospectiveLineItem = new ProspectiveLineItem()
{
    advertiserId = advertiserId,
    lineItem = lineItem
};
AvailabilityForecast forecast =
  forecastService.getAvailabilityForecast(prospectiveLineItem, options);
    

Ruby


  prospective_line_item = {
    :advertiser_id => advertiser_id,
    :line_item => line_item
  }

  # Set forecasting options.
  forecast_options = {
    :include_contending_line_items => true,
    # The field includeTargetingCriteriaBreakdown can only be set if breakdowns
    # are not mannually specified.
    # :include_targeting_criteria_breakdown => true,
    :breakdown => {
      # Break down forecast by day from start_time to end_time
      :time_windows => time_windows,
      # Break down forecast by any targeting configuration
      :targets => [
        {
          # Optional, the name field is only used to identify this breakdown in
          # the response.
          :name => 'United States',
          :targeting => {
            :inventory_targeting => targeting[:inventory_targeting],
            :geo_targeting => {
              :targeted_locations => [
                {
                  :id => '2840',
                  :display_name => 'US'
                }
              ]
            }
          }
        },
        {
          # Optional, the name field is only used to identify this breakdown in
          # the response.
          :name => 'Geneva',
          :targeting => {
            :inventory_targeting => targeting[:inventory_targeting],
            :geo_targeting => {
              :targeted_locations => [
                {
                  :id => '20133',
                  :display_name => 'Geneva'
                }
              ]
            }
          }
        }
      ]
    }
  }

  # Get forecast for the line item.
  forecast = forecast_service.get_availability_forecast(
      prospective_line_item, forecast_options)
    

投放预测

如果您想模拟多个竞争订单项的投放,可以通过 DeliveryForecast 实现此目的。

现有订单项

您可以使用现有订单项的 ID 针对这些订单项运行投放预测。

Java


  // Get the ForecastService.
  ForecastServiceInterface forecastService =
      adManagerServices.get(session, ForecastServiceInterface.class);

  DeliveryForecastOptions options = new DeliveryForecastOptions();

  DeliveryForecast forecast =
      forecastService.getDeliveryForecastByIds(Longs.toArray(lineItemIds), options);

  for (LineItemDeliveryForecast lineItemForecast : forecast.getLineItemDeliveryForecasts()) {
    String unitType = lineItemForecast.getUnitType().toString().toLowerCase();
    System.out.printf("Forecast for line item %d:%n", lineItemForecast.getLineItemId());
    System.out.printf("\t%d %s matched%n", lineItemForecast.getMatchedUnits(), unitType);
    System.out.printf("\t%d %s delivered%n", lineItemForecast.getDeliveredUnits(), unitType);
    System.out.printf(
        "\t%d %s predicted%n", lineItemForecast.getPredictedDeliveryUnits(), unitType);
  }
    

Python


  # Initialize appropriate service.
  forecast_service = client.GetService('ForecastService', version='v202402')

  # Get forecast for line item.
  forecast = forecast_service.getDeliveryForecastByIds(
      [line_item_id1, line_item_id2], {'ignoredLineItemIds': []})

  for single_forecast in forecast['lineItemDeliveryForecasts']:
    unit_type = single_forecast['unitType']
    print('Forecast for line item %d:\n\t%d %s matched\n\t%d %s delivered\n\t'
          '%d %s predicted\n' % (
              single_forecast['lineItemId'], single_forecast['matchedUnits'],
              unit_type, single_forecast['deliveredUnits'], unit_type,
              single_forecast['predictedDeliveryUnits'], unit_type))


if __name__ == '__main__':
  # Initialize client object.
  ad_manager_client = ad_manager.AdManagerClient.LoadFromStorage()
  main(ad_manager_client, LINE_ITEM_ID_1, LINE_ITEM_ID_2)

    

PHP


      $forecastService = $serviceFactory->createForecastService($session);

      // Get forecast for the line items with no options set.
      $forecast = $forecastService->getDeliveryForecastByIds(
          [$lineItemId1, $lineItemId2],
          new DeliveryForecastOptions()
      );

      // Print out forecast results.
      $lineItemDeliveryForecasts = $forecast->getLineItemDeliveryForecasts();
      foreach ($lineItemDeliveryForecasts as $lineItemForecast) {
          $unitType = strtolower($lineItemForecast->getUnitType());
          printf(
              "Forecast for line item ID %d:%s",
              $lineItemForecast->getLineItemId(),
              PHP_EOL
          );
          printf(
              "    %d %s matched%s",
              $lineItemForecast->getMatchedUnits(),
              $unitType,
              PHP_EOL
          );
          printf(
              "    %d %s delivered%s",
              $lineItemForecast->getDeliveredUnits(),
              $unitType,
              PHP_EOL
          );
          printf(
              "    %d %s predicted%s",
              $lineItemForecast->getPredictedDeliveryUnits(),
              $unitType,
              PHP_EOL
          );
      }
    

C#


using (ForecastService forecastService = user.GetService<ForecastService>())
{
// Get a delivery forecast for the line items.
DeliveryForecastOptions options = new DeliveryForecastOptions();
options.ignoredLineItemIds = new long[]
{
};
DeliveryForecast forecast = forecastService.getDeliveryForecastByIds(new long[]
{
    lineItemId1,
    lineItemId2
}, options);

// Display results.
foreach (LineItemDeliveryForecast lineItemForecast in forecast
    .lineItemDeliveryForecasts)
{
    String unitType = lineItemForecast.unitType.GetType().Name.ToLower();
    Console.WriteLine("Forecast for line item {0}:",
        lineItemForecast.lineItemId);
    Console.WriteLine("\t{0} {1} matched", lineItemForecast.matchedUnits,
        unitType);
    Console.WriteLine("\t{0} {1} delivered", lineItemForecast.deliveredUnits,
        unitType);
    Console.WriteLine("\t{0} {1} predicted",
        lineItemForecast.predictedDeliveryUnits, unitType);
}

    

Ruby


  # Get the ForecastService.
  forecast_service = ad_manager.service(:ForecastService, API_VERSION)
  # Get forecast for the line item.
  forecast = forecast_service.get_delivery_forecast_by_ids(
      [line_item_id1, line_item_id2], nil)

  unless forecast.nil? || forecast[:line_item_delivery_forecasts].nil?
    forecast[:line_item_delivery_forecasts].each do |single_forecast|
      # Display results.
      unit_type = single_forecast[:unit_type]
      puts ('Forecast for line item %d:\n\t%d %s matched\n\t%d %s ' +
          'delivered\n\t%d %s predicted\n') % [single_forecast[:line_item_id],
          single_forecast[:matched_units], unit_type,
          single_forecast[:delivered_units], unit_type,
          single_forecast[:predicted_delivery_units], unit_type]
    end
  end
    

此示例的输出结果类似于以下内容:

Forecast for line item 14678:
    100 clicks matched
    0 clicks delivered
    98 clicks predicted

如果您想从投放模拟中排除任何订单项,可以通过在 DeliveryForecastOptions 中设置相应 ID 来实现此目的。

预测性订单项

与可用性预测类似,您可以对未保留的订单项运行投放预测。为此,请在 ForecastService.getDeliveryForecast 方法中使用 ProspectiveItem 对象。

未来销售率报表

未来销售率报表可预测您的 Google Ad Manager 广告资源网可争取的展示机会数,以便您能够最大限度地提高收入和销售率。“未来销售率”报告可通过 ReportService 生成。

FAQ

我想预测很多订单项的广告资源可用情况。能否在一个请求中运行多个预测?
不可以。您必须为每个订单项或预测性订单项发出单独的广告资源预测请求。
我运行了几次预测,现在遇到了 EXCEEDED_QUOTA 错误。这是怎么回事?
预测的计算成本很高,而配额系统可确保服务的可靠性。您可以放心地等待,然后重试导致配额错误的任何预测。
导致 NO_FORECAST_YET 或 NOT_ENOUGH_INVENTORY 错误的原因是什么?
预测是根据您广告联盟的流量历史记录运行的。有时,由于没有足够的历史数据来运行预测,如需详细了解这些错误,请参阅 ForecastError 文档。
什么是 AlternativeUnitTypeForecast?
有时,了解有哪些其他广告资源会很有用。例如,在预测 CPC 订单项时,其他单元类型预测将包含有关展示次数的信息。
对于 Ad Manager 预测,我还有其他一般性问题。
请查看产品常见问题解答中是否涵盖了这些问题,或在我们的开发者论坛中提问。