REST Resource: advertisers.adGroupAds

  • Display & Video 360 API v3 has sunset and users should transition to v4.

  • The AdGroupAd resource represents a single ad associated with an ad group and includes various ad types and their details.

  • Different ad types such as MastheadAd, InStreamAd, NonSkippableAd, BumperAd, AudioAd, VideoDiscoveryAd, and VideoPerformanceAd are detailed with their specific fields and structures.

  • Common attributes for several in-stream ad types are grouped under the CommonInStreamAttribute resource.

  • Supporting resources like YoutubeVideoDetails, VideoUnavailableReason, VideoAspectRatio, ImageAsset, AdUrl, and AdUrlType provide additional context and definitions related to ad components and tracking.

Resource: AdGroupAd

A single ad associated with an ad group.

JSON representation 
{
  "name": string,
  "advertiserId": string,
  "adGroupAdId": string,
  "adGroupId": string,
  "displayName": string,
  "entityStatus": enum (EntityStatus),
  "adUrls": [
    {
      object (AdUrl)
    }
  ],

  // Union field ad_details can be only one of the following:
  "displayVideoSourceAd": {
    object (DisplayVideoSourceAd)
  },
  "mastheadAd": {
    object (MastheadAd)
  },
  "inStreamAd": {
    object (InStreamAd)
  },
  "nonSkippableAd": {
    object (NonSkippableAd)
  },
  "bumperAd": {
    object (BumperAd)
  },
  "audioAd": {
    object (AudioAd)
  },
  "videoDiscoverAd": {
    object (VideoDiscoveryAd)
  },
  "videoPerformanceAd": {
    object (VideoPerformanceAd)
  }
  // End of list of possible types for union field ad_details.
}
Fields
name

string

The resource name of the ad.
advertiserId

string (int64 format)

The unique ID of the advertiser the ad belongs to.
adGroupAdId

string (int64 format)

The unique ID of the ad. Assigned by the system.
adGroupId

string (int64 format)

The unique ID of the ad group that the ad belongs to.
displayName

string

The display name of the ad.

Must be UTF-8 encoded with a maximum size of 255 bytes.
entityStatus

enum (EntityStatus)

The entity status of the ad.
adUrls[]

object (AdUrl)

List of URLs used by the ad.
Union field ad_details. The details of the ad. ad_details can be only one of the following:
displayVideoSourceAd

object (DisplayVideoSourceAd)

Details of an ad sourced from a Display & Video 360 creative.
mastheadAd

object (MastheadAd)

Details of an ad served on the YouTube Home feed.
inStreamAd

object (InStreamAd)

Details of an in-stream ad skippable after 5 seconds, used for brand awareness or reach marketing objectives.
nonSkippableAd

object (NonSkippableAd)

Details of a non-skippable short in-stream video ad, between 6 and 15 seconds, used for reach marketing objectives.
bumperAd

object (BumperAd)

Details of a non-skippable short video ad, equal to or less than 6 seconds, used for reach.
audioAd

object (AudioAd)

Details of an audio ad used for reach marketing objectives.
videoDiscoverAd

object (VideoDiscoveryAd)

Details of an ad promoting a video that shows in places of discovery.
videoPerformanceAd

object (VideoPerformanceAd)

Details of an ad used in a video action campaign to drive actions to the business, service or product.

DisplayVideoSourceAd

The ad sourced from a DV360 creative.

JSON representation 
{
  "creativeId": string
}
Fields
creativeId

string (int64 format)

The ID of the source creative.

MastheadAd

Details for a Masthead Ad.

JSON representation 
{
  "video": {
    object (YoutubeVideoDetails)
  },
  "headline": string,
  "description": string,
  "videoAspectRatio": enum (VideoAspectRatio),
  "autoplayVideoStartMillisecond": string,
  "autoplayVideoDuration": string,
  "callToActionButtonLabel": string,
  "callToActionFinalUrl": string,
  "callToActionTrackingUrl": string,
  "showChannelArt": boolean,
  "companionYoutubeVideos": [
    {
      object (YoutubeVideoDetails)
    }
  ]
}
Fields
video

object (YoutubeVideoDetails)

The YouTube video used by the ad.
headline

string

The headline of the ad.
description

string

The description of the ad.
videoAspectRatio

enum (VideoAspectRatio)

The aspect ratio of the autoplaying YouTube video on the Masthead.
autoplayVideoStartMillisecond

string (int64 format)

The amount of time in milliseconds after which the video will start to play.
autoplayVideoDuration

string (Duration format)

The duration of time the video will autoplay.

A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".
callToActionButtonLabel

string

The text on the call-to-action button.
callToActionFinalUrl

string

The destination URL for the call-to-action button.
callToActionTrackingUrl

string

The tracking URL for the call-to-action button.
showChannelArt

boolean

Whether to show a background or banner that appears at the top of a YouTube page.
companionYoutubeVideos[]

object (YoutubeVideoDetails)

The videos that appear next to the Masthead Ad on desktop. Can be no more than two.

YoutubeVideoDetails

Details of a YouTube video.

JSON representation 
{
  "id": string,
  "unavailableReason": enum (VideoUnavailableReason)
}
Fields
id

string

The YouTube video ID which can be searched on YouTube webpage.
unavailableReason

enum (VideoUnavailableReason)

The reason why the video data is not available.

VideoUnavailableReason

Possible reasons why a video could be unavailable.

Enums
VIDEO_UNAVAILABLE_REASON_UNSPECIFIED Unknown or unspecified.
VIDEO_UNAVAILABLE_REASON_PRIVATE The video is private.
VIDEO_UNAVAILABLE_REASON_DELETED The video is deleted.

VideoAspectRatio

Possible aspect ratios for a YouTube video.

Enums
VIDEO_ASPECT_RATIO_UNSPECIFIED Not specified or unknown.
VIDEO_ASPECT_RATIO_WIDESCREEN The video is stretched and the top and bottom are cropped.
VIDEO_ASPECT_RATIO_FIXED_16_9 The video uses a fixed 16:9 aspect ratio.

InStreamAd

Details for an in-stream ad.

JSON representation 
{
  "commonInStreamAttribute": {
    object (CommonInStreamAttribute)
  },
  "customParameters": {
    string: string,
    ...
  }
}
Fields
commonInStreamAttribute

object (CommonInStreamAttribute)

Common ad attributes.
customParameters

map (key: string, value: string)

The custom parameters to pass custom values to tracking URL template.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

CommonInStreamAttribute

Common attributes for in-stream, non-skippable and bumper ads.

JSON representation 
{
  "displayUrl": string,
  "finalUrl": string,
  "trackingUrl": string,
  "actionButtonLabel": string,
  "actionHeadline": string,
  "video": {
    object (YoutubeVideoDetails)
  },
  "companionBanner": {
    object (ImageAsset)
  }
}
Fields
displayUrl

string

The webpage address that appears with the ad.
finalUrl

string

The URL address of the webpage that people reach after they click the ad.
trackingUrl

string

The URL address loaded in the background for tracking purposes.
actionButtonLabel

string

The text on the call-to-action button.
actionHeadline

string

The headline of the call-to-action banner.
video

object (YoutubeVideoDetails)

The YouTube video of the ad.
companionBanner

object (ImageAsset)

The image which shows next to the video ad.

ImageAsset

Meta data of an image asset.

JSON representation 
{
  "mimeType": string,
  "fullSize": {
    object (Dimensions)
  },
  "fileSize": string
}
Fields
mimeType

string

MIME type of the image asset.
fullSize

object (Dimensions)

Metadata for this image at its original size.
fileSize

string (int64 format)

File size of the image asset in bytes.

NonSkippableAd

Details for a non-skippable ad.

JSON representation 
{
  "commonInStreamAttribute": {
    object (CommonInStreamAttribute)
  },
  "customParameters": {
    string: string,
    ...
  }
}
Fields
commonInStreamAttribute

object (CommonInStreamAttribute)

Common ad attributes.
customParameters

map (key: string, value: string)

The custom parameters to pass custom values to tracking URL template.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

BumperAd

Details for a bumper ad.

JSON representation 
{
  "commonInStreamAttribute": {
    object (CommonInStreamAttribute)
  }
}
Fields
commonInStreamAttribute

object (CommonInStreamAttribute)

Common ad attributes.

AudioAd

Details for an audio ad.

JSON representation 
{
  "displayUrl": string,
  "finalUrl": string,
  "trackingUrl": string,
  "video": {
    object (YoutubeVideoDetails)
  }
}
Fields
displayUrl

string

The webpage address that appears with the ad.
finalUrl

string

The URL address of the webpage that people reach after they click the ad.
trackingUrl

string

The URL address loaded in the background for tracking purposes.
video

object (YoutubeVideoDetails)

The YouTube video of the ad.

VideoDiscoveryAd

Details for a video discovery ad.

JSON representation 
{
  "headline": string,
  "description1": string,
  "description2": string,
  "video": {
    object (YoutubeVideoDetails)
  },
  "thumbnail": enum (Thumbnail)
}
Fields
headline

string

The headline of ad.
description1

string

First text line for the ad.
description2

string

Second text line for the ad.
video

object (YoutubeVideoDetails)

The YouTube video the ad promotes.
thumbnail

enum (Thumbnail)

Thumbnail image used in the ad.

Thumbnail

Possible thumbnail options in Video Discovery Ads.

Enums
THUMBNAIL_UNSPECIFIED Unknown or unspecified.
THUMBNAIL_DEFAULT The default thumbnail, can be auto-generated or user-uploaded.
THUMBNAIL_1 Thumbnail 1, generated from the video.
THUMBNAIL_2 Thumbnail 2, generated from the video.
THUMBNAIL_3 Thumbnail 3, generated from the video.

VideoPerformanceAd

Details for a video performance ad.

JSON representation 
{
  "finalUrl": string,
  "trackingUrl": string,
  "actionButtonLabels": [
    string
  ],
  "headlines": [
    string
  ],
  "longHeadlines": [
    string
  ],
  "descriptions": [
    string
  ],
  "displayUrlBreadcrumb1": string,
  "displayUrlBreadcrumb2": string,
  "domain": string,
  "videos": [
    {
      object (YoutubeVideoDetails)
    }
  ],
  "customParameters": {
    string: string,
    ...
  },
  "companionBanners": [
    {
      object (ImageAsset)
    }
  ]
}
Fields
finalUrl

string

The URL address of the webpage that people reach after they click the ad.
trackingUrl

string

The URL address loaded in the background for tracking purposes.
actionButtonLabels[]

string

The list of text assets shown on the call-to-action button.
headlines[]

string

The list of headlines shown on the call-to-action banner.
longHeadlines[]

string

The list of lone headlines shown on the call-to-action banner.
descriptions[]

string

The list of descriptions shown on the call-to-action banner.
displayUrlBreadcrumb1

string

The first piece after the domain in the display URL.
displayUrlBreadcrumb2

string

The second piece after the domain in the display URL.
domain

string

The domain of the display URL.
videos[]

object (YoutubeVideoDetails)

The list of YouTube video assets used by this ad.
customParameters

map (key: string, value: string)

The custom parameters to pass custom values to tracking URL template.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
companionBanners[]

object (ImageAsset)

The list of companion banners used by this ad.

AdUrl

Additional URLs related to the ad, including beacons.

JSON representation 
{
  "type": enum (AdUrlType),
  "url": string
}
Fields
type

enum (AdUrlType)

The type of the Ad URL.
url

string

The URL string value.

AdUrlType

Possible ad URL types.

Enums
AD_URL_TYPE_UNSPECIFIED Unknown or unspecified.
AD_URL_TYPE_BEACON_IMPRESSION A 1x1 tracking pixel to ping when an impression of a creative is delivered.
AD_URL_TYPE_BEACON_EXPANDABLE_DCM_IMPRESSION Expandable DCM impression beacon. At serving time, it is expanded to several beacons.
AD_URL_TYPE_BEACON_CLICK Tracking URL to ping when the click event is triggered.
AD_URL_TYPE_BEACON_SKIP Tracking URL to ping when the skip event is triggered.

Methods

get

 Gets an ad group ad.

list

 Lists ad group ads.