---
title: "POST /v23/customers/{+customerId}:generateReachForecast"
method: POST
path: "/v23/customers/{+customerId}:generateReachForecast"
tags: ["customers"]
---

# POST /v23/customers/{+customerId}:generateReachForecast

`POST /v23/customers/{+customerId}:generateReachForecast`

Generates a reach forecast for a given targeting / product mix. List of thrown errors: [AuthenticationError]() [AuthorizationError]() [FieldError]() [HeaderError]() [InternalError]() [QuotaError]() [RangeError]() [ReachPlanError]() [RequestError]()

## Path parameters

- `customerId` string, required

## Request body

- GoogleAdsSearchads360V23ServicesGenerateReachForecastRequest — Request message for ReachPlanService.GenerateReachForecast.
  - `cookieFrequencyCap` integer — Chosen cookie frequency cap to be applied to each planned product. This is equivalent to the frequency cap exposed in Google Ads when creating a campaign, it represents the maximum number of times an ad can be shown to the same user. If not specified, no cap is applied. This field is deprecated in v4 and will eventually be removed. Use cookie_frequency_cap_setting instead.
  - `cookieFrequencyCapSetting` GoogleAdsSearchads360V23ServicesFrequencyCap — A rule specifying the maximum number of times an ad can be shown to a user over a particular time period.
    - `impressions` integer — Required. The number of impressions, inclusive.
    - `timeUnit` 'UNSPECIFIED' | 'UNKNOWN' | 'DAY' | 'WEEK' | 'MONTH' — Required. The type of time unit.
  - `targeting` GoogleAdsSearchads360V23ServicesTargeting — The targeting for which traffic metrics will be reported.
    - `plannableLocationId` string — The ID of the selected location. Plannable location IDs can be obtained from ReachPlanService.ListPlannableLocations. Requests must set either this field or `plannable_location_ids`. This field is deprecated as of V12 and will be removed in a future release. Use `plannable_location_ids` instead.
    - `ageRange` 'UNSPECIFIED' | 'UNKNOWN' | 'AGE_RANGE_18_24' | 'AGE_RANGE_18_34' | 'AGE_RANGE_18_44' | 'AGE_RANGE_18_49' | 'AGE_RANGE_18_54' | 'AGE_RANGE_18_64' | 'AGE_RANGE_18_65_UP' | 'AGE_RANGE_21_34' | 'AGE_RANGE_25_34' | 'AGE_RANGE_25_44' | 'AGE_RANGE_25_49' | 'AGE_RANGE_25_54' | 'AGE_RANGE_25_64' | 'AGE_RANGE_25_65_UP' | 'AGE_RANGE_35_44' | 'AGE_RANGE_35_49' | 'AGE_RANGE_35_54' | 'AGE_RANGE_35_64' | 'AGE_RANGE_35_65_UP' | 'AGE_RANGE_45_54' | 'AGE_RANGE_45_64' | 'AGE_RANGE_45_65_UP' | 'AGE_RANGE_50_65_UP' | 'AGE_RANGE_55_64' | 'AGE_RANGE_55_65_UP' | 'AGE_RANGE_65_UP' — Targeted age range. An unset value is equivalent to targeting all ages.
    - `devices` GoogleAdsSearchads360V23CommonDeviceInfo[] — Targeted devices. If not specified, targets all applicable devices. Applicable devices vary by product and region and can be obtained from ReachPlanService.ListPlannableProducts.
      - `type` 'UNSPECIFIED' | 'UNKNOWN' | 'MOBILE' | 'TABLET' | 'DESKTOP' | 'CONNECTED_TV' | 'OTHER' — Type of the device.
    - `audienceTargeting` GoogleAdsSearchads360V23ServicesAudienceTargeting — Audience targeting for reach forecast.
      - `userInterest` GoogleAdsSearchads360V23CommonUserInterestInfo[] — List of audiences based on user interests to be targeted.
        - `userInterestCategory` string — The UserInterest resource name.
      - `userLists` GoogleAdsSearchads360V23CommonUserListInfo[] — List of audiences based on user lists to be targeted.
        - `userList` string — The User List resource name.
    - `plannableLocationIds` string[] — The list of plannable location IDs to target with this forecast. If more than one ID is provided, all IDs must have the same `parent_country_id`. Planning for more than `parent_county` is not supported. Plannable location IDs and their `parent_country_id` can be obtained from ReachPlanService.ListPlannableLocations. Requests must set either this field or `plannable_location_id`.
    - `genders` GoogleAdsSearchads360V23CommonGenderInfo[] — Targeted genders. An unset value is equivalent to targeting MALE and FEMALE.
      - `type` 'UNSPECIFIED' | 'UNKNOWN' | 'MALE' | 'FEMALE' | 'UNDETERMINED' — Type of the gender.
    - `network` 'UNSPECIFIED' | 'UNKNOWN' | 'YOUTUBE' | 'GOOGLE_VIDEO_PARTNERS' | 'YOUTUBE_AND_GOOGLE_VIDEO_PARTNERS' — Targetable network for the ad product. If not specified, targets all applicable networks. Applicable networks vary by product and region and can be obtained from ReachPlanService.ListPlannableProducts.
  - `reachApplicationInfo` GoogleAdsSearchads360V23CommonAdditionalApplicationInfo — Additional information about the application/tool issuing the request. This field is only used by ContentCreatorInsightsService, AudienceInsightsService, and ReachPlanService APIs.
    - `applicationInstance` 'UNSPECIFIED' | 'UNKNOWN' | 'DEVELOPMENT_AND_TESTING' | 'PRODUCTION' — The instance type of the application sending the request.
    - `applicationId` string — The unique identifier of the agency proprietary application. This identifier is generated by Google. Reach out to your Google representative to request an application_id for each new application being integrated.
  - `campaignDuration` GoogleAdsSearchads360V23ServicesCampaignDuration — The duration of a planned campaign.
    - `durationInDays` integer — The duration value in days. This field cannot be combined with the date_range field.
    - `dateRange` GoogleAdsSearchads360V23CommonDateRange — A date range.
      - `startDate` string — The start date, in yyyy-mm-dd format. This date is inclusive.
      - `endDate` string — The end date, in yyyy-mm-dd format. This date is inclusive.
  - `forecastMetricOptions` GoogleAdsSearchads360V23ServicesForecastMetricOptions — Controls forecast metrics to return.
    - `includeCoview` boolean — Indicates whether to include co-view metrics in the response forecast.
  - `effectiveFrequencyLimit` GoogleAdsSearchads360V23ServicesEffectiveFrequencyLimit — Effective frequency limit.
    - `effectiveFrequencyBreakdownLimit` integer — The highest effective frequency value to include in Forecast.effective_frequency_breakdowns. This field supports frequencies 1-10, inclusive.
  - `currencyCode` string — The currency code. Three-character ISO 4217 currency code.
  - `minEffectiveFrequency` integer — Chosen minimum effective frequency (the number of times a person was exposed to the ad) for the reported reach metrics [1-10]. This won't affect the targeting, but just the reporting. If not specified, a default of 1 is applied. This field cannot be combined with the effective_frequency_limit field.
  - `plannedProducts` GoogleAdsSearchads360V23ServicesPlannedProduct[] — Required. The products to be forecast. The max number of allowed planned products is 15.
    - `conversionRate` number, double — Conversion rate as a decimal between 0 and 1, exclusive. For example: if 2% of ad interactions are expected to lead to conversions, conversion_rate should be 0.02. This field is required for DEMAND_GEN plannable products. It is not supported for other plannable products.
    - `advancedProductTargeting` GoogleAdsSearchads360V23ServicesAdvancedProductTargeting — Advanced targeting settings for products.
      - `surfaceTargetingSettings` GoogleAdsSearchads360V23ServicesSurfaceTargeting — Container for surfaces for a product. Surfaces refer to the available types of ad inventories such as In-Feed, In-Stream, and Shorts.
        - `surfaces` string[] — List of surfaces available to target.
      - `targetFrequencySettings` GoogleAdsSearchads360V23ServicesTargetFrequencySettings — Target Frequency settings for a supported product.
        - `targetFrequency` integer — Required. The target frequency goal per selected time unit.
        - `timeUnit` 'UNSPECIFIED' | 'UNKNOWN' | 'WEEKLY' | 'MONTHLY' — Required. The time unit used to describe the time frame for target_frequency.
      - `youtubeSelectSettings` GoogleAdsSearchads360V23ServicesYouTubeSelectSettings — Request settings for YouTube Select Lineups
        - `lineupId` string, int64 — Lineup for YouTube Select Targeting.
    - `budgetMicros` string, int64 — Required. Maximum budget allocation in micros for the selected product. The value is specified in the selected planning currency_code. For example: 1 000 000$ = 1 000 000 000 000 micros.
    - `plannableProductCode` string — Required. Selected product for planning. The code associated with the ad product (for example: Trueview, Bumper). To list the available plannable product codes use ReachPlanService.ListPlannableProducts.
  - `customerReachGroup` string — The name of the customer being planned for. This is a user-defined value.

## Response `200`

Successful response

---

[API](https://skmtc.net/google/apis/searchads360.md) · [All operations](https://skmtc.net/google/apis/searchads360/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/google/searchads360/versions/40d087435afd/schema)