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

# POST /v4/advertisers/{advertisersId}/reachForecast:generateReachForecast

`POST /v4/advertisers/{advertisersId}/reachForecast:generateReachForecast`

## Request

- Base URL: `https://displayvideo.googleapis.com`
- URL: `https://displayvideo.googleapis.com/v4/advertisers/{advertisersId}/reachForecast:generateReachForecast`
- Auth: OAuth 2 and OAuth 2
  - Implicit: `https://accounts.google.com/o/oauth2/auth`
  - Scopes: `https://www.googleapis.com/auth/display-video`
  - Authorization code: `https://accounts.google.com/o/oauth2/auth`
  - Token URL: `https://accounts.google.com/o/oauth2/token` scopes: `https://www.googleapis.com/auth/display-video`
- TypeScript: <https://skmtc.dev/google/apis/displayvideo/docs/v4/advertisers/:advertisersId/reachForecast:generateReachForecast/post.ts> (a function with typed inputs; its response is checked against the schema)

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

- `advertisersId` 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

- GenerateReachForecastResponse: Response message for ReachForecastService.GenerateReachForecast.
  - `onTargetAudienceMetrics` OnTargetAudienceMetrics: Estimated audience sizes for a targeted geography.
    - `censusAudienceSize` string, int64: Size of the audience based on the census data of the targeted geography.
    - `youtubeAudienceSize` string, int64: Estimated size of the YouTube audience.
  - `reachCurve` ReachCurve: The generated reach curve.
    - `reachForecasts` ReachForecast[]: Points along the curve, ordered by cost.
      - `costMicros` string, int64: Total cost for this point in micros.
      - `forecast` PlannedProductForecast: Performance metrics for a forecast point.
        - `onTargetCoviewImpressions` string, int64: Number of on-target impressions including co-viewers.
        - `onTargetCoviewReach` string, int64: Number of unique people reached that match the on-target definition including co-viewers.
        - `onTargetImpressions` string, int64: Number of on-target impressions.
        - `onTargetReach` string, int64: Number of unique people reached that match the on-target definition.
        - `totalCoviewImpressions` string, int64: Total number of impressions including co-viewers.
        - `totalCoviewReach` string, int64: Total number of unique people reached including co-viewers.
        - `totalImpressions` string, int64: Total number of impressions.
        - `totalReach` string, int64: Total number of unique people reached.
        - `trueviewViews` string, int64: Number of TrueView views.
        - `viewableImpressions` string, int64: Number of viewable impressions.
      - `plannedProductReachForecasts` PlannedProductReachForecast[]: Breakdown for individual products at this cost point.
        - `costMicros` string, int64: The cost in micros for this product.
        - `plannableProductCode` string: The code for the product.
        - `plannedProductForecast` PlannedProductForecast: Performance metrics for a forecast point.
          - `onTargetCoviewImpressions` string, int64: Number of on-target impressions including co-viewers.
          - `onTargetCoviewReach` string, int64: Number of unique people reached that match the on-target definition including co-viewers.
          - `onTargetImpressions` string, int64: Number of on-target impressions.
          - `onTargetReach` string, int64: Number of unique people reached that match the on-target definition.
          - `totalCoviewImpressions` string, int64: Total number of impressions including co-viewers.
          - `totalCoviewReach` string, int64: Total number of unique people reached including co-viewers.
          - `totalImpressions` string, int64: Total number of impressions.
          - `totalReach` string, int64: Total number of unique people reached.
          - `trueviewViews` string, int64: Number of TrueView views.
          - `viewableImpressions` string, int64: Number of viewable impressions.

---

[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/d80b56b6703a?raw)