Caution: You are viewing documentation for the API's REST interface. Most of our official client libraries use gRPC. See the REST Introduction for details.

AdGroupCriterion

An ad group criterion.

JSON representation 
{
  "resourceName": string,
  "displayName": string,
  "status": enum (AdGroupCriterionStatus),
  "qualityInfo": {
    object (QualityInfo)
  },
  "type": enum (CriterionType),
  "systemServingStatus": enum (CriterionSystemServingStatus),
  "approvalStatus": enum (AdGroupCriterionApprovalStatus),
  "disapprovalReasons": [
    string
  ],
  "labels": [
    string
  ],
  "effectiveCpcBidSource": enum (BiddingSource),
  "effectiveCpmBidSource": enum (BiddingSource),
  "effectiveCpvBidSource": enum (BiddingSource),
  "effectivePercentCpcBidSource": enum (BiddingSource),
  "positionEstimates": {
    object (PositionEstimates)
  },
  "finalUrls": [
    string
  ],
  "finalMobileUrls": [
    string
  ],
  "urlCustomParameters": [
    {
      object (CustomParameter)
    }
  ],
  "criterionId": string,
  "adGroup": string,
  "negative": boolean,
  "bidModifier": number,
  "cpcBidMicros": string,
  "cpmBidMicros": string,
  "cpvBidMicros": string,
  "percentCpcBidMicros": string,
  "effectiveCpcBidMicros": string,
  "effectiveCpmBidMicros": string,
  "effectiveCpvBidMicros": string,
  "effectivePercentCpcBidMicros": string,
  "finalUrlSuffix": string,
  "trackingUrlTemplate": string,

  // Union field criterion can be only one of the following:
  "keyword": {
    object (KeywordInfo)
  },
  "placement": {
    object (PlacementInfo)
  },
  "mobileAppCategory": {
    object (MobileAppCategoryInfo)
  },
  "mobileApplication": {
    object (MobileApplicationInfo)
  },
  "listingGroup": {
    object (ListingGroupInfo)
  },
  "ageRange": {
    object (AgeRangeInfo)
  },
  "gender": {
    object (GenderInfo)
  },
  "incomeRange": {
    object (IncomeRangeInfo)
  },
  "parentalStatus": {
    object (ParentalStatusInfo)
  },
  "userList": {
    object (UserListInfo)
  },
  "youtubeVideo": {
    object (YouTubeVideoInfo)
  },
  "youtubeChannel": {
    object (YouTubeChannelInfo)
  },
  "topic": {
    object (TopicInfo)
  },
  "userInterest": {
    object (UserInterestInfo)
  },
  "webpage": {
    object (WebpageInfo)
  },
  "appPaymentModel": {
    object (AppPaymentModelInfo)
  },
  "customAffinity": {
    object (CustomAffinityInfo)
  },
  "customIntent": {
    object (CustomIntentInfo)
  },
  "customAudience": {
    object (CustomAudienceInfo)
  },
  "combinedAudience": {
    object (CombinedAudienceInfo)
  },
  "audience": {
    object (AudienceInfo)
  }
  // End of list of possible types for union field criterion.
}
Fields
resourceName

string

Immutable. The resource name of the ad group criterion. Ad group criterion resource names have the form:

customers/{customerId}/adGroupCriteria/{adGroupId}~{criterionId}
displayName

string

Output only. The display name of the criterion.

This field is ignored for mutates.
status

enum (AdGroupCriterionStatus)

The status of the criterion.

This is the status of the ad group criterion entity, set by the client. Note: UI reports may incorporate additional information that affects whether a criterion is eligible to run. In some cases a criterion that's REMOVED in the API can still show as enabled in the UI. For example, campaigns by default show to users of all age ranges unless excluded. The UI will show each age range as "enabled", since they're eligible to see the ads; but AdGroupCriterion.status will show "removed", since no positive criterion was added.
qualityInfo

object (QualityInfo)

Output only. Information regarding the quality of the criterion.
type

enum (CriterionType)

Output only. The type of the criterion.
systemServingStatus

enum (CriterionSystemServingStatus)

Output only. Serving status of the criterion.
approvalStatus

enum (AdGroupCriterionApprovalStatus)

Output only. Approval status of the criterion.
disapprovalReasons[]

string

Output only. List of disapproval reasons of the criterion.

The different reasons for disapproving a criterion can be found here: https://support.google.com/adspolicy/answer/6008942

This field is read-only.
labels[]

string

Output only. The resource names of labels attached to this ad group criterion.
effectiveCpcBidSource

enum (BiddingSource)

Output only. Source of the effective CPC bid.
effectiveCpmBidSource

enum (BiddingSource)

Output only. Source of the effective CPM bid.
effectiveCpvBidSource

enum (BiddingSource)

Output only. Source of the effective CPV bid.
effectivePercentCpcBidSource

enum (BiddingSource)

Output only. Source of the effective Percent CPC bid.
positionEstimates

object (PositionEstimates)

Output only. Estimates for criterion bids at various positions.
finalUrls[]

string

The list of possible final URLs after all cross-domain redirects for the ad.
finalMobileUrls[]

string

The list of possible final mobile URLs after all cross-domain redirects.
urlCustomParameters[]

object (CustomParameter)

The list of mappings used to substitute custom parameter tags in a trackingUrlTemplate, finalUrls, or mobile_final_urls.
criterionId

string (int64 format)

Output only. The ID of the criterion.

This field is ignored for mutates.
adGroup

string

Immutable. The ad group to which the criterion belongs.
negative

boolean

Immutable. Whether to target (false) or exclude (true) the criterion.

This field is immutable. To switch a criterion from positive to negative, remove then re-add it.
bidModifier

number

The modifier for the bid when the criterion matches. The modifier must be in the range: 0.1 - 10.0. Most targetable criteria types support modifiers.
cpcBidMicros

string (int64 format)

The CPC (cost-per-click) bid.
cpmBidMicros

string (int64 format)

The CPM (cost-per-thousand viewable impressions) bid.
cpvBidMicros

string (int64 format)

The CPV (cost-per-view) bid.
percentCpcBidMicros

string (int64 format)

The CPC bid amount, expressed as a fraction of the advertised price for some good or service. The valid range for the fraction is [0,1) and the value stored here is 1,000,000 * [fraction].
effectiveCpcBidMicros

string (int64 format)

Output only. The effective CPC (cost-per-click) bid.
effectiveCpmBidMicros

string (int64 format)

Output only. The effective CPM (cost-per-thousand viewable impressions) bid.
effectiveCpvBidMicros

string (int64 format)

Output only. The effective CPV (cost-per-view) bid.
effectivePercentCpcBidMicros

string (int64 format)

Output only. The effective Percent CPC bid amount.
finalUrlSuffix

string

URL template for appending params to final URL.
trackingUrlTemplate

string

The URL template for constructing a tracking URL.

Union field criterion. The ad group criterion.

Exactly one must be set. criterion can be only one of the following:
keyword

object (KeywordInfo)

Immutable. Keyword.
placement

object (PlacementInfo)

Immutable. Placement.
mobileAppCategory

object (MobileAppCategoryInfo)

Immutable. Mobile app category.
mobileApplication

object (MobileApplicationInfo)

Immutable. Mobile application.
listingGroup

object (ListingGroupInfo)

Immutable. Listing group.
ageRange

object (AgeRangeInfo)

Immutable. Age range.
gender

object (GenderInfo)

Immutable. Gender.
incomeRange

object (IncomeRangeInfo)

Immutable. Income range.
parentalStatus

object (ParentalStatusInfo)

Immutable. Parental status.
userList

object (UserListInfo)

Immutable. User List. The Similar Audiences sunset starts May 2023. Refer to https://ads-developers.googleblog.com/2022/11/announcing-deprecation-and-sunset-of.html for other options.
youtubeVideo

object (YouTubeVideoInfo)

Immutable. YouTube Video.
youtubeChannel

object (YouTubeChannelInfo)

Immutable. YouTube Channel.
topic

object (TopicInfo)

Immutable. Topic.
userInterest

object (UserInterestInfo)

Immutable. User Interest.
webpage

object (WebpageInfo)

Immutable. Webpage
appPaymentModel

object (AppPaymentModelInfo)

Immutable. App Payment Model.
customAffinity

object (CustomAffinityInfo)

Immutable. Custom Affinity.
customIntent

object (CustomIntentInfo)

Immutable. Custom Intent.
customAudience

object (CustomAudienceInfo)

Immutable. Custom Audience.
combinedAudience

object (CombinedAudienceInfo)

Immutable. Combined Audience.
audience

object (AudienceInfo)

Immutable. Audience.

AdGroupCriterionStatus

The possible statuses of an AdGroupCriterion.

Enums
UNSPECIFIED No value has been specified.
UNKNOWN

The received value is not known in this version.

This is a response-only value.
ENABLED The ad group criterion is enabled.
PAUSED The ad group criterion is paused.
REMOVED The ad group criterion is removed.

QualityInfo

A container for ad group criterion quality information.

JSON representation 
{
  "creativeQualityScore": enum (QualityScoreBucket),
  "postClickQualityScore": enum (QualityScoreBucket),
  "searchPredictedCtr": enum (QualityScoreBucket),
  "qualityScore": integer
}
Fields
creativeQualityScore

enum (QualityScoreBucket)

Output only. The performance of the ad compared to other advertisers.
postClickQualityScore

enum (QualityScoreBucket)

Output only. The quality score of the landing page.
searchPredictedCtr

enum (QualityScoreBucket)

Output only. The click-through rate compared to that of other advertisers.
qualityScore

integer

Output only. The quality score.

This field may not be populated if Google does not have enough information to determine a value.

CriterionSystemServingStatus

Enumerates criterion system serving statuses.

Enums
UNSPECIFIED Not specified.
UNKNOWN The value is unknown in this version.
ELIGIBLE Eligible.
RARELY_SERVED Low search volume.

AdGroupCriterionApprovalStatus

Enumerates AdGroupCriterion approval statuses.

Enums
UNSPECIFIED Not specified.
UNKNOWN The value is unknown in this version.
APPROVED Approved.
DISAPPROVED Disapproved.
PENDING_REVIEW Pending Review.
UNDER_REVIEW Under review.

PositionEstimates

Estimates for criterion bids at various positions.

JSON representation 
{
  "firstPageCpcMicros": string,
  "firstPositionCpcMicros": string,
  "topOfPageCpcMicros": string,
  "estimatedAddClicksAtFirstPositionCpc": string,
  "estimatedAddCostAtFirstPositionCpc": string
}
Fields
firstPageCpcMicros

string (int64 format)

Output only. The estimate of the CPC bid required for ad to be shown on first page of search results.
firstPositionCpcMicros

string (int64 format)

Output only. The estimate of the CPC bid required for ad to be displayed in first position, at the top of the first page of search results.
topOfPageCpcMicros

string (int64 format)

Output only. The estimate of the CPC bid required for ad to be displayed at the top of the first page of search results.
estimatedAddClicksAtFirstPositionCpc

string (int64 format)

Output only. Estimate of how many clicks per week you might get by changing your keyword bid to the value in firstPositionCpcMicros.
estimatedAddCostAtFirstPositionCpc

string (int64 format)

Output only. Estimate of how your cost per week might change when changing your keyword bid to the value in firstPositionCpcMicros.

ListingGroupInfo

A listing group criterion.

JSON representation 
{
  "type": enum (ListingGroupType),
  "caseValue": {
    object (ListingDimensionInfo)
  },
  "parentAdGroupCriterion": string
}
Fields
type

enum (ListingGroupType)

Type of the listing group.
caseValue

object (ListingDimensionInfo)

Dimension value with which this listing group is refining its parent. Undefined for the root group.
parentAdGroupCriterion

string

Resource name of ad group criterion which is the parent listing group subdivision. Null for the root group.

ListingGroupType

The type of the listing group.

Enums
UNSPECIFIED Not specified.
UNKNOWN Used for return value only. Represents value unknown in this version.
SUBDIVISION Subdivision of products along some listing dimension. These nodes are not used by serving to target listing entries, but is purely to define the structure of the tree.
UNIT Listing group unit that defines a bid.

AppPaymentModelInfo

An app payment model criterion.

JSON representation 
{
  "type": enum (AppPaymentModelType)
}
Fields
type

enum (AppPaymentModelType)

Type of the app payment model.

AppPaymentModelType

Enum describing possible app payment models.

Enums
UNSPECIFIED Not specified.
UNKNOWN Used for return value only. Represents value unknown in this version.
PAID Represents paid-for apps.

CustomIntentInfo

A custom intent criterion. A criterion of this type is only targetable.

JSON representation 
{
  "customIntent": string
}
Fields
customIntent

string

The CustomInterest resource name.