AdGroupCriterion

An ad group criterion. The adGroupCriterion report only returns criteria that were explicitly added to the ad group.

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)
    }
  ],
  "primaryStatusReasons": [
    enum (AdGroupCriterionPrimaryStatusReason)
  ],
  "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,
  "primaryStatus": enum (AdGroupCriterionPrimaryStatus),

  // 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)
  },
  "location": {
    object (LocationInfo)
  },
  "language": {
    object (LanguageInfo)
  }
  // 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.
primaryStatusReasons[]

enum (AdGroupCriterionPrimaryStatusReason)

Output only. The primary status reasons for the ad group criterion.
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.
primaryStatus

enum (AdGroupCriterionPrimaryStatus)

Output only. The primary status for the ad group criterion.

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.
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.
location

object (LocationInfo)

Immutable. Location.
language

object (LanguageInfo)

Immutable. Language.

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.

AdGroupCriterionPrimaryStatus

Enum describing the possible ad group criterion primary status. Provides insight into why an ad group criterion is not serving or not serving optimally.

Enums
UNSPECIFIED Not specified.
UNKNOWN Used for return value only. Represents value unknown in this version.
ELIGIBLE The ad group criterion is eligible to serve.
PAUSED The ad group criterion is paused.
REMOVED The ad group criterion is removed.
PENDING The ad group criterion is pending.
NOT_ELIGIBLE The ad group criterion is not eligible to serve.

AdGroupCriterionPrimaryStatusReason

Enum describing the possible Ad Group Criterion primary status reasons. Provides insight into why an Ad Group Criterion is not serving or not serving optimally. These reasons are aggregated to determine an overall Ad Group Criterion primary status.

Enums
UNSPECIFIED Not specified.
UNKNOWN Used for return value only. Represents unknown value in this version.
CAMPAIGN_PENDING The user-specified time for this campaign to start is in the future. Contributes to AdGroupCriterionPrimaryStatus.PENDING.
CAMPAIGN_CRITERION_NEGATIVE The ad group criterion is overridden by negative campaign criterion. Contributes to AdGroupCriterionPrimaryStatus.NOT_ELIGIBLE.
CAMPAIGN_PAUSED The user-specified campaign status is paused. Contributes to AdGroupCriterionPrimaryStatus.PAUSED.
CAMPAIGN_REMOVED The user-specified campaign status is removed. Contributes to AdGroupCriterionPrimaryStatus.REMOVED.
CAMPAIGN_ENDED The user-specified time for this campaign to end has passed. Contributes to AdGroupCriterionPrimaryStatus.ENDED.
AD_GROUP_PAUSED The user-specified ad group status is paused. Contributes to AdGroupCriterionPrimaryStatus.PAUSED.
AD_GROUP_REMOVED The user-specified ad group status is removed. Contributes to AdGroupCriterionPrimaryStatus.REMOVED.
AD_GROUP_CRITERION_DISAPPROVED The ad group criterion is disapproved by the ads approval system. Contributes to AdGroupCriterionPrimaryStatus.NOT_ELIGIBLE.
AD_GROUP_CRITERION_RARELY_SERVED The ad group criterion is rarely served. Contributes to AdGroupCriterionPrimaryStatus.NOT_ELIGIBLE.
AD_GROUP_CRITERION_LOW_QUALITY The ad group criterion has a low quality score. Contributes to AdGroupCriterionPrimaryStatus.LIMITED.
AD_GROUP_CRITERION_UNDER_REVIEW The ad group criterion is under review. Contributes to AdGroupCriterionPrimaryStatus.PENDING.
AD_GROUP_CRITERION_PENDING_REVIEW The ad group criterion is pending review. Contributes to AdGroupCriterionPrimaryStatus.NOT_ELIGIBLE.
AD_GROUP_CRITERION_BELOW_FIRST_PAGE_BID The ad group criterion's bid is below the value necessary to serve on the first page. Contributes to AdGroupCriterionPrimaryStatus.LIMITED.
AD_GROUP_CRITERION_NEGATIVE The ad group criterion is negative. Contributes to AdGroupCriterionPrimaryStatus.NOT_ELIGIBLE.
AD_GROUP_CRITERION_RESTRICTED The ad group criterion is restricted. Contributes to AdGroupCriterionPrimaryStatus.NOT_ELIGIBLE.
AD_GROUP_CRITERION_PAUSED The user-specified ad group criterion status is paused. Contributes to AdGroupCriterionPrimaryStatus.PAUSED.
AD_GROUP_CRITERION_PAUSED_DUE_TO_LOW_ACTIVITY The ad group criterion has been paused due to prolonged low activity in serving. Contributes to AdGroupCriterionPrimaryStatus.PAUSED.
AD_GROUP_CRITERION_REMOVED The user-specified ad group criterion status is removed. Contributes to AdGroupCriterionPrimaryStatus.REMOVED.

ListingGroupInfo

A listing group criterion.

JSON representation 
{
  "type": enum (ListingGroupType),
  "caseValue": {
    object (ListingDimensionInfo)
  },
  "parentAdGroupCriterion": string,
  "path": {
    object (ListingDimensionPath)
  }
}
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.
path

object (ListingDimensionPath)

The path of dimensions defining this listing 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.

ListingDimensionPath

The path of dimensions defining a listing group.

JSON representation 
{
  "dimensions": [
    {
      object (ListingDimensionInfo)
    }
  ]
}
Fields
dimensions[]

object (ListingDimensionInfo)

The complete path of dimensions through the listing group hierarchy, from the root (excluding the root itself) to this listing group.

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.