GoogleAdsGoogleadsV25Services__GenerateReachForecastRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/google-ads/json-schema/google-ads-google-ads-googleads-v25-services-generate-reach-forecast-request-schema.json",
  "title": "GoogleAdsGoogleadsV25Services__GenerateReachForecastRequest",
  "description": "Request message for ReachPlanService.GenerateReachForecast.",
  "x-generated": "2026-11-04",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/google-ads-customers-api-openapi.yml#/components/schemas/GoogleAdsGoogleadsV25Services__GenerateReachForecastRequest",
  "type": "object",
  "properties": {
    "minEffectiveFrequency": {
      "type": "integer",
      "description": "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.",
      "format": "int32"
    },
    "targeting": {
      "$ref": "#/$defs/GoogleAdsGoogleadsV25Services__Targeting",
      "description": "The targeting to be applied to all products selected in the product mix. This is planned targeting: execution details might vary based on the advertising product, consult an implementation specialist. See specific metrics for details on how targeting affects them."
    },
    "plannedProducts": {
      "description": "Required. The products to be forecast. The max number of allowed planned products is 15.",
      "items": {
        "$ref": "#/$defs/GoogleAdsGoogleadsV25Services__PlannedProduct"
      },
      "type": "array"
    },
    "customerReachGroup": {
      "type": "string",
      "description": "The name of the customer being planned for. This is a user-defined value."
    },
    "currencyCode": {
      "type": "string",
      "description": "The currency code. Three-character ISO 4217 currency code."
    },
    "campaignDuration": {
      "$ref": "#/$defs/GoogleAdsGoogleadsV25Services__CampaignDuration",
      "description": "Required. Campaign duration."
    },
    "effectiveFrequencyLimit": {
      "description": "The highest minimum effective frequency (the number of times a person was exposed to the ad) value [1-10] to include in Forecast.effective_frequency_breakdowns. If not specified, Forecast.effective_frequency_breakdowns will not be provided. The effective frequency value provided here will also be used as the minimum effective frequency for the reported reach metrics. This field cannot be combined with the min_effective_frequency field.",
      "$ref": "#/$defs/GoogleAdsGoogleadsV25Services__EffectiveFrequencyLimit"
    },
    "forecastMetricOptions": {
      "description": "Controls the forecast metrics returned in the response.",
      "$ref": "#/$defs/GoogleAdsGoogleadsV25Services__ForecastMetricOptions"
    },
    "reachApplicationInfo": {
      "$ref": "#/$defs/GoogleAdsGoogleadsV25Common__AdditionalApplicationInfo",
      "description": "Optional. Additional information on the application issuing the request."
    },
    "cookieFrequencyCapSetting": {
      "$ref": "#/$defs/GoogleAdsGoogleadsV25Services__FrequencyCap",
      "description": "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 during a specified time interval. If not specified, a default of 0 (no cap) is applied. This field replaces the deprecated `cookie_frequency_cap` field."
    }
  },
  "$defs": {
    "GoogleAdsGoogleadsV25Common__AdditionalApplicationInfo": {
      "description": "Additional information about the application/tool issuing the request. This field is only used by ContentCreatorInsightsService, AudienceInsightsService, and ReachPlanService APIs.",
      "type": "object",
      "properties": {
        "applicationId": {
          "description": "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.",
          "type": "string"
        },
        "applicationInstance": {
          "description": "The instance type of the application sending the request.",
          "type": "string",
          "x-enumDescriptions": [
            "Not specified.",
            "The value is unknown in this version.",
            "The instance is for development and testing purposes.",
            "The instance is for production purposes."
          ],
          "enum": [
            "UNSPECIFIED",
            "UNKNOWN",
            "DEVELOPMENT_AND_TESTING",
            "PRODUCTION"
          ]
        }
      }
    },
    "GoogleAdsGoogleadsV25Common__DateRange": {
      "type": "object",
      "properties": {
        "startDate": {
          "type": "string",
          "description": "The start date, in yyyy-mm-dd format. This date is inclusive."
        },
        "endDate": {
          "description": "The end date, in yyyy-mm-dd format. This date is inclusive.",
          "type": "string"
        }
      },
      "description": "A date range."
    },
    "GoogleAdsGoogleadsV25Common__DeviceInfo": {
      "description": "A device criterion.",
      "type": "object",
      "properties": {
        "type": {
          "x-enumDescriptions": [
            "Not specified.",
            "The value is unknown in this version.",
            "Mobile devices with full browsers.",
            "Tablets with full browsers.",
            "Computers.",
            "Smart TVs and game consoles.",
            "Other device types."
          ],
          "enum": [
            "UNSPECIFIED",
            "UNKNOWN",
            "MOBILE",
            "TABLET",
            "DESKTOP",
            "CONNECTED_TV",
            "OTHER"
          ],
          "description": "Type of the device.",
          "type": "string"
        }
      }
    },
    "GoogleAdsGoogleadsV25Common__GenderInfo": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "description": "Type of the gender.",
          "x-enumDescriptions": [
            "Not specified.",
            "Used for return value only. Represents value unknown in this version.",
            "Male.",
            "Female.",
            "Undetermined gender."
          ],
          "enum": [
            "UNSPECIFIED",
            "UNKNOWN",
            "MALE",
            "FEMALE",
            "UNDETERMINED"
          ]
        }
      },
      "description": "A gender criterion."
    },
    "GoogleAdsGoogleadsV25Common__UserInterestInfo": {
      "description": "Represents a particular interest-based topic to be targeted.",
      "type": "object",
      "properties": {
        "userInterestCategory": {
          "type": "string",
          "description": "The UserInterest resource name."
        }
      }
    },
    "GoogleAdsGoogleadsV25Common__UserListInfo": {
      "type": "object",
      "properties": {
        "userList": {
          "type": "string",
          "description": "The User List resource name."
        }
      },
      "description": "A User List criterion. Represents a user list that is defined by the advertiser to be targeted."
    },
    "GoogleAdsGoogleadsV25Services__AdvancedProductTargeting": {
      "description": "Advanced targeting settings for products.",
      "type": "object",
      "properties": {
        "youtubeSelectSettings": {
          "$ref": "#/$defs/GoogleAdsGoogleadsV25Services__YouTubeSelectSettings",
          "description": "Settings for YouTube Select targeting."
        },
        "surfaceTargetingSettings": {
          "description": "Surface targeting settings for this product.",
          "$ref": "#/$defs/GoogleAdsGoogleadsV25Services__SurfaceTargeting"
        },
        "targetFrequencySettings": {
          "$ref": "#/$defs/GoogleAdsGoogleadsV25Services__TargetFrequencySettings",
          "description": "Settings for a Target frequency campaign. Must be set when selecting the TARGET_FREQUENCY product. See https://support.google.com/google-ads/answer/12400225 for more information about Target Frequency campaigns."
        }
      }
    },
    "GoogleAdsGoogleadsV25Services__AudienceTargeting": {
      "description": "Audience targeting for reach forecast.",
      "type": "object",
      "properties": {
        "userInterest": {
          "type": "array",
          "description": "List of audiences based on user interests to be targeted.",
          "items": {
            "$ref": "#/$defs/GoogleAdsGoogleadsV25Common__UserInterestInfo"
          }
        },
        "userLists": {
          "type": "array",
          "description": "List of audiences based on user lists to be targeted.",
          "items": {
            "$ref": "#/$defs/GoogleAdsGoogleadsV25Common__UserListInfo"
          }
        }
      }
    },
    "GoogleAdsGoogleadsV25Services__CampaignDuration": {
      "description": "The duration of a planned campaign.",
      "type": "object",
      "properties": {
        "durationInDays": {
          "type": "integer",
          "description": "The duration value in days. This field cannot be combined with the date_range field.",
          "format": "int32"
        },
        "dateRange": {
          "$ref": "#/$defs/GoogleAdsGoogleadsV25Common__DateRange",
          "description": "Date range of the campaign. Dates are in the yyyy-mm-dd format and inclusive. The end date must be < 1 year in the future and the date range must be <= 92 days long. This field cannot be combined with the duration_in_days field."
        }
      }
    },
    "GoogleAdsGoogleadsV25Services__EffectiveFrequencyLimit": {
      "description": "Effective frequency limit.",
      "type": "object",
      "properties": {
        "effectiveFrequencyBreakdownLimit": {
          "description": "The highest effective frequency value to include in Forecast.effective_frequency_breakdowns. This field supports frequencies 1-10, inclusive.",
          "type": "integer",
          "format": "int32"
        }
      }
    },
    "GoogleAdsGoogleadsV25Services__ForecastMetricOptions": {
      "description": "Controls forecast metrics to return.",
      "type": "object",
      "properties": {
        "includeCoview": {
          "type": "boolean",
          "description": "Indicates whether to include co-view metrics in the response forecast."
        }
      }
    },
    "GoogleAdsGoogleadsV25Services__FrequencyCap": {
      "description": "A rule specifying the maximum number of times an ad can be shown to a user over a particular time period.",
      "type": "object",
      "properties": {
        "timeUnit": {
          "type": "string",
          "description": "Required. The type of time unit.",
          "x-enumDescriptions": [
            "Not specified.",
            "Used for return value only. Represents value unknown in this version.",
            "The cap would define limit per one day.",
            "The cap would define limit per one week.",
            "The cap would define limit per one month."
          ],
          "enum": [
            "UNSPECIFIED",
            "UNKNOWN",
            "DAY",
            "WEEK",
            "MONTH"
          ]
        },
        "impressions": {
          "description": "Required. The number of impressions, inclusive.",
          "type": "integer",
          "format": "int32"
        }
      }
    },
    "GoogleAdsGoogleadsV25Services__PlannedProduct": {
      "description": "A product being planned for reach.",
      "type": "object",
      "properties": {
        "plannableProductCode": {
          "type": "string",
          "description": "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."
        },
        "budgetMicros": {
          "format": "int64",
          "description": "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.",
          "type": "string"
        },
        "conversionRate": {
          "format": "double",
          "description": "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.",
          "type": "number"
        },
        "advancedProductTargeting": {
          "$ref": "#/$defs/GoogleAdsGoogleadsV25Services__AdvancedProductTargeting",
          "description": "Targeting settings for the selected product. To list the available targeting for each product use ReachPlanService.ListPlannableProducts."
        }
      }
    },
    "GoogleAdsGoogleadsV25Services__SurfaceTargeting": {
      "type": "object",
      "properties": {
        "surfaces": {
          "type": "array",
          "description": "List of surfaces available to target.",
          "items": {
            "type": "string",
            "x-enumDescriptions": [
              "Not specified.",
              "The value is unknown in this version.",
              "Discover feed ad surface.",
              "Gmail ad surface.",
              "In-Feed ad surface.",
              "In-Stream bumper ad surface.",
              "In-Stream non-skippable ad surface.",
              "In-Stream skippable ad surface.",
              "Shorts ad surface.",
              "Google Display Network ad surface.",
              "In-Stream non-skippable (30 seconds) ad surface."
            ],
            "enum": [
              "UNSPECIFIED",
              "UNKNOWN",
              "DISCOVER_FEED",
              "GMAIL",
              "IN_FEED",
              "IN_STREAM_BUMPER",
              "IN_STREAM_NON_SKIPPABLE",
              "IN_STREAM_SKIPPABLE",
              "SHORTS",
              "GOOGLE_DISPLAY_NETWORK",
              "IN_STREAM_NON_SKIPPABLE_THIRTY_SECONDS"
            ]
          }
        }
      },
      "description": "Container for surfaces for a product. Surfaces refer to the available types of ad inventories such as In-Feed, In-Stream, and Shorts."
    },
    "GoogleAdsGoogleadsV25Services__TargetFrequencySettings": {
      "type": "object",
      "properties": {
        "timeUnit": {
          "description": "Required. The time unit used to describe the time frame for target_frequency.",
          "type": "string",
          "x-enumDescriptions": [
            "Not specified.",
            "Used for return value only. Represents value unknown in this version.",
            "Optimize bidding to reach Target Frequency in a week.",
            "Optimize bidding to reach Target Frequency in a month."
          ],
          "enum": [
            "UNSPECIFIED",
            "UNKNOWN",
            "WEEKLY",
            "MONTHLY"
          ]
        },
        "targetFrequency": {
          "type": "integer",
          "description": "Required. The target frequency goal per selected time unit.",
          "format": "int32"
        }
      },
      "description": "Target Frequency settings for a supported product."
    },
    "GoogleAdsGoogleadsV25Services__Targeting": {
      "description": "The targeting for which traffic metrics will be reported.",
      "type": "object",
      "properties": {
        "genders": {
          "description": "Targeted genders. An unset value is equivalent to targeting MALE and FEMALE.",
          "items": {
            "$ref": "#/$defs/GoogleAdsGoogleadsV25Common__GenderInfo"
          },
          "type": "array"
        },
        "audienceTargeting": {
          "description": "Targeted audiences. If not specified, does not target any specific audience.",
          "$ref": "#/$defs/GoogleAdsGoogleadsV25Services__AudienceTargeting"
        },
        "plannableLocationIds": {
          "description": "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.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "ageRange": {
          "x-enumDescriptions": [
            "Not specified.",
            "The value is unknown in this version.",
            "Between 18 and 24 years old.",
            "Between 18 and 34 years old.",
            "Between 18 and 44 years old.",
            "Between 18 and 49 years old.",
            "Between 18 and 54 years old.",
            "Between 18 and 64 years old.",
            "Between 18 and 65+ years old.",
            "Between 21 and 34 years old.",
            "Between 21 and 44 years old.",
            "Between 21 and 49 years old.",
            "Between 21 and 54 years old.",
            "Between 21 and 64 years old.",
            "Between 21 and 65+ years old.",
            "Between 25 and 34 years old.",
            "Between 25 and 44 years old.",
            "Between 25 and 49 years old.",
            "Between 25 and 54 years old.",
            "Between 25 and 64 years old.",
            "Between 25 and 65+ years old.",
            "Between 35 and 44 years old.",
            "Between 35 and 49 years old.",
            "Between 35 and 54 years old.",
            "Between 35 and 64 years old.",
            "Between 35 and 65+ years old.",
            "Between 45 and 54 years old.",
            "Between 45 and 64 years old.",
            "Between 45 and 65+ years old.",
            "Between 50 and 65+ years old.",
            "Between 55 and 64 years old.",
            "Between 55 and 65+ years old.",
            "65 years old and beyond."
          ],
          "enum": [
            "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_21_44",
            "AGE_RANGE_21_49",
            "AGE_RANGE_21_54",
            "AGE_RANGE_21_64",
            "AGE_RANGE_21_65_UP",
            "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"
          ],
          "description": "Targeted age range. An unset value is equivalent to targeting all ages.",
          "type": "string"
        },
        "network": {
          "x-enumDescriptions": [
            "Not specified.",
            "Used as a return value only. Represents value unknown in this version.",
            "YouTube network.",
            "Google Video Partners (GVP) network.",
            "A combination of the YouTube network and the Google Video Partners network."
          ],
          "enum": [
            "UNSPECIFIED",
            "UNKNOWN",
            "YOUTUBE",
            "GOOGLE_VIDEO_PARTNERS",
            "YOUTUBE_AND_GOOGLE_VIDEO_PARTNERS"
          ],
          "type": "string",
          "description": "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."
        },
        "devices": {
          "description": "Targeted devices. If not specified, targets all applicable devices. Applicable devices vary by product and region and can be obtained from ReachPlanService.ListPlannableProducts.",
          "items": {
            "$ref": "#/$defs/GoogleAdsGoogleadsV25Common__DeviceInfo"
          },
          "type": "array"
        }
      }
    },
    "GoogleAdsGoogleadsV25Services__YouTubeSelectSettings": {
      "description": "Request settings for YouTube Select Lineups",
      "type": "object",
      "properties": {
        "lineupId": {
          "type": "string",
          "description": "Lineup for YouTube Select Targeting.",
          "format": "int64"
        }
      }
    }
  }
}