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.

REST Resource: customers.adGroups

Resource: AdGroup

An ad group.

JSON representation
{
  "resourceName": string,
  "status": enum (AdGroupStatus),
  "type": enum (AdGroupType),
  "adRotationMode": enum (AdGroupAdRotationMode),
  "urlCustomParameters": [
    {
      object (CustomParameter)
    }
  ],
  "explorerAutoOptimizerSetting": {
    object (ExplorerAutoOptimizerSetting)
  },
  "displayCustomBidDimension": enum (TargetingDimension),
  "targetingSetting": {
    object (TargetingSetting)
  },
  "effectiveTargetCpaSource": enum (BiddingSource),
  "effectiveTargetRoasSource": enum (BiddingSource),
  "labels": [
    string
  ],
  "excludedParentAssetFieldTypes": [
    enum (AssetFieldType)
  ],
  "id": string,
  "name": string,
  "baseAdGroup": string,
  "trackingUrlTemplate": string,
  "campaign": string,
  "cpcBidMicros": string,
  "cpmBidMicros": string,
  "targetCpaMicros": string,
  "cpvBidMicros": string,
  "targetCpmMicros": string,
  "targetRoas": number,
  "percentCpcBidMicros": string,
  "finalUrlSuffix": string,
  "effectiveTargetCpaMicros": string,
  "effectiveTargetRoas": number
}
Fields
resourceName

string

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

customers/{customerId}/adGroups/{adGroupId}

status

enum (AdGroupStatus)

The status of the ad group.

type

enum (AdGroupType)

Immutable. The type of the ad group.

adRotationMode

enum (AdGroupAdRotationMode)

The ad rotation mode of the ad group.

urlCustomParameters[]

object (CustomParameter)

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

explorerAutoOptimizerSetting

object (ExplorerAutoOptimizerSetting)

Settings for the Display Campaign Optimizer, initially termed "Explorer".

displayCustomBidDimension

enum (TargetingDimension)

Allows advertisers to specify a targeting dimension on which to place absolute bids. This is only applicable for campaigns that target only the display network and not search.

targetingSetting

object (TargetingSetting)

Setting for targeting related features.

effectiveTargetCpaSource

enum (BiddingSource)

Output only. Source of the effective target CPA. This field is read-only.

effectiveTargetRoasSource

enum (BiddingSource)

Output only. Source of the effective target ROAS. This field is read-only.

labels[]

string

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

excludedParentAssetFieldTypes[]

enum (AssetFieldType)

The asset field types that should be excluded from this ad group. Asset links with these field types will not be inherited by this ad group from the upper levels.

id

string (int64 format)

Output only. The ID of the ad group.

name

string

The name of the ad group.

This field is required and should not be empty when creating new ad groups.

It must contain fewer than 255 UTF-8 full-width characters.

It must not contain any null (code point 0x0), NL line feed (code point 0xA) or carriage return (code point 0xD) characters.

baseAdGroup

string

Output only. For draft or experiment ad groups, this field is the resource name of the base ad group from which this ad group was created. If a draft or experiment ad group does not have a base ad group, then this field is null.

For base ad groups, this field equals the ad group resource name.

This field is read-only.

trackingUrlTemplate

string

The URL template for constructing a tracking URL.

campaign

string

Immutable. The campaign to which the ad group belongs.

cpcBidMicros

string (int64 format)

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

cpmBidMicros

string (int64 format)

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

targetCpaMicros

string (int64 format)

The target CPA (cost-per-acquisition). If the ad group's campaign bidding strategy is TargetCpa or MaximizeConversions (with its targetCpa field set), then this field overrides the target CPA specified in the campaign's bidding strategy. Otherwise, this value is ignored.

cpvBidMicros

string (int64 format)

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

targetCpmMicros

string (int64 format)

Average amount in micros that the advertiser is willing to pay for every thousand times the ad is shown.

targetRoas

number

The target ROAS (return-on-ad-spend) override. If the ad group's campaign bidding strategy is TargetRoas or MaximizeConversionValue (with its targetRoas field set), then this field overrides the target ROAS specified in the campaign's bidding strategy. Otherwise, this value is ignored.

percentCpcBidMicros

string (int64 format)

The percent 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].

finalUrlSuffix

string

URL template for appending params to Final URL.

effectiveTargetCpaMicros

string (int64 format)

Output only. The effective target CPA (cost-per-acquisition). This field is read-only.

effectiveTargetRoas

number

Output only. The effective target ROAS (return-on-ad-spend). This field is read-only.

AdGroupStatus

The possible statuses of an ad group.

Enums
UNSPECIFIED The status has not been specified.
UNKNOWN

The received value is not known in this version.

This is a response-only value.

ENABLED The ad group is enabled.
PAUSED The ad group is paused.
REMOVED The ad group is removed.

AdGroupType

Enum listing the possible types of an ad group.

Enums
UNSPECIFIED The type has not been specified.
UNKNOWN

The received value is not known in this version.

This is a response-only value.

SEARCH_STANDARD The default ad group type for googleAds.search campaigns.
DISPLAY_STANDARD The default ad group type for Display campaigns.
SHOPPING_PRODUCT_ADS The ad group type for Shopping campaigns serving standard product ads.
HOTEL_ADS The default ad group type for Hotel campaigns.
SHOPPING_SMART_ADS The type for ad groups in Smart Shopping campaigns.
VIDEO_BUMPER Short unskippable in-stream video ads.
VIDEO_TRUE_VIEW_IN_STREAM TrueView (skippable) in-stream video ads.
VIDEO_TRUE_VIEW_IN_DISPLAY TrueView in-display video ads.
VIDEO_NON_SKIPPABLE_IN_STREAM Unskippable in-stream video ads.
VIDEO_OUTSTREAM Outstream video ads.
SEARCH_DYNAMIC_ADS Ad group type for Dynamic googleAds.search Ads ad groups.
SHOPPING_COMPARISON_LISTING_ADS The type for ad groups in Shopping Comparison Listing campaigns.
PROMOTED_HOTEL_ADS The ad group type for Promoted Hotel ad groups.
VIDEO_RESPONSIVE Video responsive ad groups.
VIDEO_EFFICIENT_REACH Video efficient reach ad groups.

AdGroupAdRotationMode

The possible ad rotation modes of an ad group.

Enums
UNSPECIFIED The ad rotation mode has not been specified.
UNKNOWN

The received value is not known in this version.

This is a response-only value.

OPTIMIZE Optimize ad group ads based on clicks or conversions.
ROTATE_FOREVER Rotate evenly forever.

ExplorerAutoOptimizerSetting

Settings for the Display Campaign Optimizer, initially named "Explorer". Learn more about automatic targeting.

JSON representation
{
  "optIn": boolean
}
Fields
optIn

boolean

Indicates whether the optimizer is turned on.

Methods

get

Returns the requested ad group in full detail.

mutate

Creates, updates, or removes ad groups.