在寻找 REST API？Ad Manager API（Beta 版）现已发布。

此页面由 Cloud Translation API 翻译。

预测

简介

本指南介绍了 Google Ads 中的预测功能 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);

在 GitHub 上查看

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
    }
})

在 GitHub 上查看

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);

在 GitHub 上查看

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);

在 GitHub 上查看

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
  }
})

在 GitHub 上查看

广告资源预测

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>

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

现有 LineItem

您可以使用现有订单项的 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);

在 GitHub 上查看

Python

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

  # 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()))

在 GitHub 上查看

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
      );

在 GitHub 上查看

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);

在 GitHub 上查看

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

在 GitHub 上查看

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

100 clicks matched.
2 contending line items.

潜在 LineItem

或者，您可以实例化一个预测性订单项并进行预测，而无需存储数据为此，请实例化本地订单项对象，并将其设置为 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);

在 GitHub 上查看

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)

在 GitHub 上查看

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
      );

在 GitHub 上查看

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);

在 GitHub 上查看

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)

在 GitHub 上查看

投放预测

如果您想模拟多个竞争订单项的投放，可以执行以下操作：使用 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);
  }

在 GitHub 上查看

Python

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

  # 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)

在 GitHub 上查看

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
          );
      }

在 GitHub 上查看

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);
}

在 GitHub 上查看

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

在 GitHub 上查看

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

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

如果您想从投放模拟中排除任何订单项，请按以下步骤操作：因此，您可以在 DeliveryForecastOptions。

预测性订单项

与广告资源预测类似，您可以在线运行投放预测未持久保留的项。为此，请在 ForecastService.getDeliveryForecast 方法。

未来销售率报告

未来销售率报告可预测您的借助 Google Ad Manager 广告联盟，您可以最大限度地提高收入销售率您可以通过 ReportService 运行未来销售率报告。

常见问题解答

我想预测很多订单项的广告资源可用情况。我可以在一个请求中运行多个预测吗？: 不会。您必须为每个订单项单独发出广告资源预测请求订单项或预测性订单项。
我运行了很多预测，但现在出现了 EXCEEDED_QUOTA 个错误。这是怎么回事？: 预测需要大量的计算资源，而配额系统可确保服务可靠性您可以安心地等待一段时间，并重新尝试运行预测结果发生配额错误。
导致 NO_FORECAST_YET 或 NOT_ENOUGH_INVENTORY 错误的原因是什么？: 预测的依据是您广告联盟的流量历史记录。有时，历史数据不足以运行预测。有关请参阅 ForecastError 文档。
什么是 AlternativeUnitTypeForecast？: 有时，了解哪些其他广告资源可供使用会很有用。对于例如，在预测 CPC 行替代单位类型，预测数据将包含展示次数相关信息。
对于 Ad Manager 预测，我还有其他一般性问题。: 查看产品是否涵盖这些内容常见问题解答，或在我们的开发者网站上咨询论坛。