---
title: "POST /v4/advertisers/{+advertiserId}/reachForecast:generateReachForecast"
method: POST
path: "/v4/advertisers/{+advertiserId}/reachForecast:generateReachForecast"
tags: ["advertisers"]
---

# POST /v4/advertisers/{+advertiserId}/reachForecast:generateReachForecast

`POST /v4/advertisers/{+advertiserId}/reachForecast:generateReachForecast`

## Request

- Base URL: `https://displayvideo.googleapis.com`
- URL: `https://displayvideo.googleapis.com/v4/advertisers/{+advertiserId}/reachForecast:generateReachForecast`
- Auth: OAuth 2 (implicit, authorization URL `https://accounts.google.com/o/oauth2/auth`, scopes: `https://www.googleapis.com/auth/display-video`) and OAuth 2 (authorization code, authorization URL `https://accounts.google.com/o/oauth2/auth`, token URL `https://accounts.google.com/o/oauth2/token`, scopes: `https://www.googleapis.com/auth/display-video`)

Generates a reach forecast for a given advertiser and targeting configuration. API support for generating reach forecasts and retrieving related metadata is in beta. This method is only available to allowlisted users.

## Path parameters

- `advertiserId` string, required

## Request body

- GenerateReachForecastRequest: Request message for ReachForecastService.GenerateReachForecast.
  - `campaignDuration` CampaignDuration: The duration of the reach plan.
    - `dateRange` DateRange: A date range.
      - `endDate` Date: Represents a whole or partial calendar date, such as a birthday. The time of day and time zone are either specified elsewhere or are insignificant. The date is relative to the Gregorian Calendar. This can represent one of the following: * A full date, with non-zero year, month, and day values. * A month and day, with a zero year (for example, an anniversary). * A year on its own, with a zero month and a zero day. * A year and month, with a zero day (for example, a credit card expiration date). Related types: * google.type.TimeOfDay * google.type.DateTime * google.protobuf.Timestamp
        - `day` integer: Day of a month. Must be from 1 to 31 and valid for the year and month, or 0 to specify a year by itself or a year and month where the day isn't significant.
        - `month` integer: Month of a year. Must be from 1 to 12, or 0 to specify a year without a month and day.
        - `year` integer: Year of the date. Must be from 1 to 9999, or 0 to specify a date without a year.
      - `startDate` Date: Represents a whole or partial calendar date, such as a birthday. The time of day and time zone are either specified elsewhere or are insignificant. The date is relative to the Gregorian Calendar. This can represent one of the following: * A full date, with non-zero year, month, and day values. * A month and day, with a zero year (for example, an anniversary). * A year on its own, with a zero month and a zero day. * A year and month, with a zero day (for example, a credit card expiration date). Related types: * google.type.TimeOfDay * google.type.DateTime * google.protobuf.Timestamp
        - `day` integer: Day of a month. Must be from 1 to 31 and valid for the year and month, or 0 to specify a year by itself or a year and month where the day isn't significant.
        - `month` integer: Month of a year. Must be from 1 to 12, or 0 to specify a year without a month and day.
        - `year` integer: Year of the date. Must be from 1 to 9999, or 0 to specify a date without a year.
    - `durationDays` integer: Required. The number of days the plan covers.
  - `currencyCode` string: Required. The currency code for the plan in ISO 4217 format.
  - `minEffectiveFrequency` integer: Optional. The minimum effective frequency for the reported reach metrics. This is the smallest number of times a customer must be exposed to the ad for it to be considered effective. This setting only impacts reporting. Must be between 1 and 10, inclusive. If not specified, a default of 1 is applied.
  - `plannedProducts` PlannedProduct[]: Required. The list of line items to include in the forecast.
    - `advancedProductTargeting` AdvancedProductTargeting: Product-specific targeting overrides.
      - `ageRange` 'PLANNABLE_AGE_RANGE_UNSPECIFIED' | 'PLANNABLE_AGE_RANGE_18_24' | 'PLANNABLE_AGE_RANGE_18_34' | 'PLANNABLE_AGE_RANGE_18_44' | 'PLANNABLE_AGE_RANGE_18_49' | 'PLANNABLE_AGE_RANGE_18_54' | 'PLANNABLE_AGE_RANGE_18_64' | 'PLANNABLE_AGE_RANGE_18_65_UP' | 'PLANNABLE_AGE_RANGE_21_34' | 'PLANNABLE_AGE_RANGE_21_44' | 'PLANNABLE_AGE_RANGE_21_49' | 'PLANNABLE_AGE_RANGE_21_54' | 'PLANNABLE_AGE_RANGE_21_64' | 'PLANNABLE_AGE_RANGE_21_65_UP' | 'PLANNABLE_AGE_RANGE_25_34' | 'PLANNABLE_AGE_RANGE_25_44' | 'PLANNABLE_AGE_RANGE_25_49' | 'PLANNABLE_AGE_RANGE_25_54' | 'PLANNABLE_AGE_RANGE_25_64' | 'PLANNABLE_AGE_RANGE_25_65_UP' | 'PLANNABLE_AGE_RANGE_35_44' | 'PLANNABLE_AGE_RANGE_35_49' | 'PLANNABLE_AGE_RANGE_35_54' | 'PLANNABLE_AGE_RANGE_35_64' | 'PLANNABLE_AGE_RANGE_35_65_UP' | 'PLANNABLE_AGE_RANGE_45_54' | 'PLANNABLE_AGE_RANGE_45_64' | 'PLANNABLE_AGE_RANGE_45_65_UP' | 'PLANNABLE_AGE_RANGE_50_65_UP' | 'PLANNABLE_AGE_RANGE_55_64' | 'PLANNABLE_AGE_RANGE_55_65_UP' | 'PLANNABLE_AGE_RANGE_65_UP': Optional. The age range to target.
      - `dateRange` DateRange: A date range.
        - `endDate` Date: Represents a whole or partial calendar date, such as a birthday. The time of day and time zone are either specified elsewhere or are insignificant. The date is relative to the Gregorian Calendar. This can represent one of the following: * A full date, with non-zero year, month, and day values. * A month and day, with a zero year (for example, an anniversary). * A year on its own, with a zero month and a zero day. * A year and month, with a zero day (for example, a credit card expiration date). Related types: * google.type.TimeOfDay * google.type.DateTime * google.protobuf.Timestamp
          - `day` integer: Day of a month. Must be from 1 to 31 and valid for the year and month, or 0 to specify a year by itself or a year and month where the day isn't significant.
          - `month` integer: Month of a year. Must be from 1 to 12, or 0 to specify a year without a month and day.
          - `year` integer: Year of the date. Must be from 1 to 9999, or 0 to specify a date without a year.
        - `startDate` Date: Represents a whole or partial calendar date, such as a birthday. The time of day and time zone are either specified elsewhere or are insignificant. The date is relative to the Gregorian Calendar. This can represent one of the following: * A full date, with non-zero year, month, and day values. * A month and day, with a zero year (for example, an anniversary). * A year on its own, with a zero month and a zero day. * A year and month, with a zero day (for example, a credit card expiration date). Related types: * google.type.TimeOfDay * google.type.DateTime * google.protobuf.Timestamp
          - `day` integer: Day of a month. Must be from 1 to 31 and valid for the year and month, or 0 to specify a year by itself or a year and month where the day isn't significant.
          - `month` integer: Month of a year. Must be from 1 to 12, or 0 to specify a year without a month and day.
          - `year` integer: Year of the date. Must be from 1 to 9999, or 0 to specify a date without a year.
      - `devices` string[]: Optional. The devices to target.
      - `frequencyCap` FrequencyCap: Settings that control the number of times a user may be shown with the same ad during a given time period.
        - `maxImpressions` integer: The maximum number of times a user may be shown the same ad during this period. Must be greater than 0. Required when unlimited is `false` and max_views is not set.
        - `maxViews` integer: Optional. The maximum number of times a user may click-through or fully view an ad during this period until it is no longer served to them. Must be greater than 0. Only applicable to YouTube and Partners resources. Required when unlimited is `false` and max_impressions is not set.
        - `timeUnit` 'TIME_UNIT_UNSPECIFIED' | 'TIME_UNIT_LIFETIME' | 'TIME_UNIT_MONTHS' | 'TIME_UNIT_WEEKS' | 'TIME_UNIT_DAYS' | 'TIME_UNIT_HOURS' | 'TIME_UNIT_MINUTES': The time unit in which the frequency cap will be applied. Required when unlimited is `false`.
        - `timeUnitCount` integer: The number of time_unit the frequency cap will last. Required when unlimited is `false`. The following restrictions apply based on the value of time_unit: * `TIME_UNIT_MONTHS` - must be 1 * `TIME_UNIT_WEEKS` - must be between 1 and 4 * `TIME_UNIT_DAYS` - must be between 1 and 6 * `TIME_UNIT_HOURS` - must be between 1 and 23 * `TIME_UNIT_MINUTES` - must be between 1 and 59
        - `unlimited` boolean: Whether unlimited frequency capping is applied. When this field is set to `true`, the remaining frequency cap fields are not applicable.
      - `genders` string[]: Optional. The gender options to target.
      - `network` 'PLANNABLE_NETWORK_UNSPECIFIED' | 'PLANNABLE_NETWORK_YOUTUBE' | 'PLANNABLE_NETWORK_GOOGLE_VIDEO_PARTNERS' | 'PLANNABLE_NETWORK_YOUTUBE_AND_GOOGLE_VIDEO_PARTNERS': Optional. The network to target.
      - `plannableLocationIds` string[]: Optional. Plannable location IDs to target.
      - `surfaceTargetingSettings` SurfaceTargetingSettings: Surface targeting selection.
        - `surfaces` string[]: Optional. The surfaces to target.
      - `targetFrequency` TargetFrequency: Setting that controls the average number of times the ads will show to the same person over a certain period of time.
        - `targetCount` string, int64: The target number of times, on average, the ads will be shown to the same person in the timespan dictated by time_unit and time_unit_count.
        - `timeUnit` 'TIME_UNIT_UNSPECIFIED' | 'TIME_UNIT_LIFETIME' | 'TIME_UNIT_MONTHS' | 'TIME_UNIT_WEEKS' | 'TIME_UNIT_DAYS' | 'TIME_UNIT_HOURS' | 'TIME_UNIT_MINUTES': The unit of time in which the target frequency will be applied. The following time unit is applicable: * `TIME_UNIT_WEEKS` * `TIME_UNIT_MONTHS`
        - `timeUnitCount` integer: The number of time_unit the target frequency will last. The following restrictions apply based on the value of time_unit: * `TIME_UNIT_WEEKS` - must be 1 * `TIME_UNIT_MONTHS` - must be 1
      - `userInterestIds` string[]: Optional. The user interest IDs to target. Plannable user interests can be retrieved using the `RetrievePlannableUserInterests` method.
      - `userListIds` string[]: Optional. The user list IDs to target. Plannable user lists can be retrieved using the `RetrievePlannableUserInterests` method.
      - `youtubeSelectSettings` YouTubeSelectSettings: Settings for YouTube Select Lineups.
        - `lineupId` string, int64: Optional. The ID of the YouTube Select Lineup.
    - `budgetMicros` string, int64: Required. The budget for this product in micros.
    - `plannableProductCode` string: Required. The code for the product, e.g. "VIDEO_REACH_CAMPAIGN".
  - `targeting` Targeting: Targeting settings for a planned campaign.
    - `ageRange` 'PLANNABLE_AGE_RANGE_UNSPECIFIED' | 'PLANNABLE_AGE_RANGE_18_24' | 'PLANNABLE_AGE_RANGE_18_34' | 'PLANNABLE_AGE_RANGE_18_44' | 'PLANNABLE_AGE_RANGE_18_49' | 'PLANNABLE_AGE_RANGE_18_54' | 'PLANNABLE_AGE_RANGE_18_64' | 'PLANNABLE_AGE_RANGE_18_65_UP' | 'PLANNABLE_AGE_RANGE_21_34' | 'PLANNABLE_AGE_RANGE_21_44' | 'PLANNABLE_AGE_RANGE_21_49' | 'PLANNABLE_AGE_RANGE_21_54' | 'PLANNABLE_AGE_RANGE_21_64' | 'PLANNABLE_AGE_RANGE_21_65_UP' | 'PLANNABLE_AGE_RANGE_25_34' | 'PLANNABLE_AGE_RANGE_25_44' | 'PLANNABLE_AGE_RANGE_25_49' | 'PLANNABLE_AGE_RANGE_25_54' | 'PLANNABLE_AGE_RANGE_25_64' | 'PLANNABLE_AGE_RANGE_25_65_UP' | 'PLANNABLE_AGE_RANGE_35_44' | 'PLANNABLE_AGE_RANGE_35_49' | 'PLANNABLE_AGE_RANGE_35_54' | 'PLANNABLE_AGE_RANGE_35_64' | 'PLANNABLE_AGE_RANGE_35_65_UP' | 'PLANNABLE_AGE_RANGE_45_54' | 'PLANNABLE_AGE_RANGE_45_64' | 'PLANNABLE_AGE_RANGE_45_65_UP' | 'PLANNABLE_AGE_RANGE_50_65_UP' | 'PLANNABLE_AGE_RANGE_55_64' | 'PLANNABLE_AGE_RANGE_55_65_UP' | 'PLANNABLE_AGE_RANGE_65_UP': Optional. The age range to target.
    - `devices` string[]: Optional. The devices to target.
    - `genders` string[]: Optional. The gender options to target.
    - `plannableLocationIds` string[]: Required. IDs of plannable locations to target. Plannable locations can be retrieved using the `RetrievePlannableLocations` method.

## Response `200`

Successful response

## Changes

- **2026-10-10** `52cdb4885336`: 2 breaking
  - removed the request body
  - removed the media type `*/*` for the response with the status `200`
- **2026-10-10** `0f73dc785c76`: 8 info
  - added the optional property `reachCurve/reachForecasts/items/forecast/onTargetCoviewImpressions` to the response with the `200` status
  - added the optional property `reachCurve/reachForecasts/items/forecast/onTargetCoviewReach` to the response with the `200` status
  - added the optional property `reachCurve/reachForecasts/items/forecast/totalCoviewImpressions` to the response with the `200` status
  - added the optional property `reachCurve/reachForecasts/items/forecast/totalCoviewReach` to the response with the `200` status
  - …4 more

[Operation history](https://skmtc.dev/google/apis/displayvideo/changes/v4/advertisers/:advertiserId/reachForecast:generateReachForecast/post.md)

---

[API](https://skmtc.dev/google/apis/displayvideo.md) - [All operations](https://skmtc.dev/google/apis/displayvideo/llms.txt) - [OpenAPI document](https://skmtc.dev/google/apis/displayvideo/revisions/6329126f9fb6?raw)