--- title: "POST /v23/customers/{customersId}:generateReachForecast" method: POST path: "/v23/customers/{customersId}:generateReachForecast" tags: ["customers"] --- # POST /v23/customers/{customersId}:generateReachForecast `POST /v23/customers/{customersId}:generateReachForecast` ## Request - Base URL: `https://searchads360.googleapis.com` - URL: `https://searchads360.googleapis.com/v23/customers/{customersId}:generateReachForecast` - Auth: OAuth 2 and OAuth 2 - Implicit: `https://accounts.google.com/o/oauth2/auth` - Scopes: `https://www.googleapis.com/auth/doubleclicksearch` - Authorization code: `https://accounts.google.com/o/oauth2/auth` - Token URL: `https://accounts.google.com/o/oauth2/token` scopes: `https://www.googleapis.com/auth/doubleclicksearch` - TypeScript: (a function with typed inputs; its response is checked against the schema) 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 - `customersId` string, required ## Request body - GoogleAdsSearchads360V23ServicesGenerateReachForecastRequest: Request message for ReachPlanService.GenerateReachForecast. - `campaignDuration` GoogleAdsSearchads360V23ServicesCampaignDuration: The duration of a planned campaign. - `dateRange` GoogleAdsSearchads360V23CommonDateRange: A date range. - `endDate` string: The end date, in yyyy-mm-dd format. This date is inclusive. - `startDate` string: The start date, in yyyy-mm-dd format. This date is inclusive. - `durationInDays` integer: The duration value in days. This field cannot be combined with the date_range field. - `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. - `currencyCode` string: The currency code. Three-character ISO 4217 currency code. - `customerReachGroup` string: The name of the customer being planned for. This is a user-defined value. - `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. - `forecastMetricOptions` GoogleAdsSearchads360V23ServicesForecastMetricOptions: Controls forecast metrics to return. - `includeCoview` boolean: Indicates whether to include co-view metrics in the response forecast. - `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. - `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. - `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. - `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. - `reachApplicationInfo` GoogleAdsSearchads360V23CommonAdditionalApplicationInfo: Additional information about the application/tool issuing the request. This field is only used by ContentCreatorInsightsService, AudienceInsightsService, and ReachPlanService APIs. - `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. - `applicationInstance` 'UNSPECIFIED' | 'UNKNOWN' | 'DEVELOPMENT_AND_TESTING' | 'PRODUCTION': The instance type of the application sending the request. - `targeting` GoogleAdsSearchads360V23ServicesTargeting: The targeting for which traffic metrics will be reported. - `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. - `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. - `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. - `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. - `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. - `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`. ## Response `200` Successful response - GoogleAdsSearchads360V23ServicesGenerateReachForecastResponse: Response message containing the generated reach curve. - `onTargetAudienceMetrics` GoogleAdsSearchads360V23ServicesOnTargetAudienceMetrics: Audience metrics for the planned products. These metrics consider the following targeting dimensions: - Location - PlannableAgeRange - Gender - AudienceTargeting (only for youtube_audience_size) - `censusAudienceSize` string, int64: Reference audience size matching the considered targeting for Census. - `youtubeAudienceSize` string, int64: Reference audience size matching the considered targeting for YouTube. - `reachCurve` GoogleAdsSearchads360V23ServicesReachCurve: The reach curve for the planned products. - `reachForecasts` GoogleAdsSearchads360V23ServicesReachForecast[]: All points on the reach curve. - `costMicros` string, int64: The cost in micros. - `forecast` GoogleAdsSearchads360V23ServicesForecast: Forecasted traffic metrics for the planned products and targeting. - `conversions` number, double: The number of conversions. This metric is only available for DEMAND_GEN plannable products. See https://support.google.com/google-ads/answer/2375431 for more information on conversions. - `effectiveFrequencyBreakdowns` GoogleAdsSearchads360V23ServicesEffectiveFrequencyBreakdown[]: A list of effective frequency forecasts. The list is ordered starting with 1+ and ending with the value set in GenerateReachForecastRequest.effective_frequency_limit. If no effective_frequency_limit was set, this list will be empty. - `effectiveCoviewReach` string, int64: The number of users (including co-viewing users) reached for the associated effective_frequency value. - `effectiveFrequency` integer: The effective frequency [1-10]. - `onTargetEffectiveCoviewReach` string, int64: The number of users (including co-viewing users) reached for the associated effective_frequency value within the specified plan demographic. - `onTargetReach` string, int64: The number of unique people reached at least effective_frequency times that exactly matches the Targeting. Note that a minimum number of unique people must be reached in order for data to be reported. If the minimum number is not met, the on_target_reach value will be rounded to 0. - `totalReach` string, int64: Total number of unique people reached at least effective_frequency times. This includes people that may fall outside the specified Targeting. Note that a minimum number of unique people must be reached in order for data to be reported. If the minimum number is not met, the total_reach value will be rounded to 0. - `onTargetCoviewImpressions` string, int64: Number of ad impressions that exactly matches the Targeting including co-viewers. - `onTargetCoviewReach` string, int64: Number of unique people reached that exactly matches the Targeting including co-viewers. - `onTargetImpressions` string, int64: Number of ad impressions that exactly matches the Targeting. - `onTargetReach` string, int64: Number of unique people reached at least GenerateReachForecastRequest.min_effective_frequency or GenerateReachForecastRequest.effective_frequency_limit times that exactly matches the Targeting. Note that a minimum number of unique people must be reached in order for data to be reported. If the minimum number is not met, the on_target_reach value will be rounded to 0. - `totalCoviewImpressions` string, int64: Total number of ad impressions including co-viewers. This includes impressions that may fall outside the specified Targeting, due to insufficient information on signed-in users. - `totalCoviewReach` string, int64: Number of unique people reached including co-viewers. This includes people that may fall outside the specified Targeting. - `totalImpressions` string, int64: Total number of ad impressions. This includes impressions that may fall outside the specified Targeting, due to insufficient information on signed-in users. - `totalReach` string, int64: Total number of unique people reached at least GenerateReachForecastRequest.min_effective_frequency or GenerateReachForecastRequest.effective_frequency_limit times. This includes people that may fall outside the specified Targeting. Note that a minimum number of unique people must be reached in order for data to be reported. If the minimum number is not met, the total_reach value will be rounded to 0. - `trueviewViews` string, int64: Number of ad views forecasted for the specified product and targeting. A TrueView View is counted when a viewer views a larger portion or the entirety of an ad beyond an impression. See https://support.google.com/google-ads/answer/2375431 for more information on TrueView Views. - `viewableImpressions` string, int64: Number of times the ad's impressions were considered viewable. See https://support.google.com/google-ads/answer/7029393 for more information about what makes an ad viewable and how viewability is measured. - `plannedProductReachForecasts` GoogleAdsSearchads360V23ServicesPlannedProductReachForecast[]: The forecasted allocation and traffic metrics for each planned product at this point on the reach curve. - `costMicros` string, int64: The cost in micros. This may differ from the product's input allocation if one or more planned products cannot fulfill the budget because of limited inventory. - `plannableProductCode` string: Selected product for planning. The product codes returned are within the set of the ones returned by ListPlannableProducts when using the same location ID. - `plannedProductForecast` GoogleAdsSearchads360V23ServicesPlannedProductForecast: Forecasted traffic metrics for a planned product. - `averageFrequency` number, double: The number of times per selected time unit a user will see an ad, averaged over the number of time units in the forecast length. This field will only be populated for a Target Frequency campaign. See https://support.google.com/google-ads/answer/12400225 for more information about Target Frequency campaigns. - `conversions` number, double: The number of conversions. This metric is only available for DEMAND_GEN plannable products. See https://support.google.com/google-ads/answer/2375431 for more information on conversions. - `onTargetCoviewImpressions` string, int64: Number of ad impressions that exactly matches the Targeting including co-viewers. - `onTargetCoviewReach` string, int64: Number of unique people reached that exactly matches the Targeting including co-viewers. - `onTargetImpressions` string, int64: Number of ad impressions that exactly matches the Targeting. - `onTargetReach` string, int64: Number of unique people reached that exactly matches the Targeting. Note that a minimum number of unique people must be reached in order for data to be reported. If the minimum number is not met, the on_target_reach value will be rounded to 0. - `totalCoviewImpressions` string, int64: Total number of ad impressions including co-viewers. This includes impressions that may fall outside the specified Targeting, due to insufficient information on signed-in users. - `totalCoviewReach` string, int64: Number of unique people reached including co-viewers. This includes people that may fall outside the specified Targeting. - `totalImpressions` string, int64: Total number of ad impressions. This includes impressions that may fall outside the specified Targeting, due to insufficient information on signed-in users. - `totalReach` string, int64: Number of unique people reached. This includes people that may fall outside the specified Targeting. Note that a minimum number of unique people must be reached in order for data to be reported. If the minimum number is not met, the total_reach value will be rounded to 0. - `trueviewViews` string, int64: Number of ad views forecasted for the specified product and targeting. A TrueView View is counted when a viewer views a larger portion or the entirety of an ad beyond an impression. See https://support.google.com/google-ads/answer/2375431 for more information on TrueView Views. - `viewableImpressions` string, int64: Number of times the ad's impressions were considered viewable. See https://support.google.com/google-ads/answer/7029393 for more information about what makes an ad viewable and how viewability is measured. --- [API](https://skmtc.dev/google/apis/searchads360.md) - [All operations](https://skmtc.dev/google/apis/searchads360/llms.txt) - [OpenAPI document](https://skmtc.dev/google/apis/searchads360/revisions/4a4511f84b18?raw)