Ad Types

Page Summary

This guide explains how to create, retrieve, and report on various Google Ads types using Google Ads scripts.
Scripts can create ads using the newAd() method on AdGroup instances, which returns an AdBuilderSpace for building different ad types.
To access fields specific to an ad's type, use the asType() method to create an AdViewSpace , but ensure the ad's type is known to avoid errors.
The ad_group_ad view can be used in reporting to query type-specific ad fields alongside regular statistics.

Google Ads supports a variety of ad types, such as text, image, and mobile ads. This guide covers how to create, retrieve, and report on ads using Google Ads scripts. For an overview of all ad types supported by Google Ads, see the API guide .

Creation

Scripts can create ads using the newAd() method on AdGroup instances. This returns an AdBuilderSpace that creates builders for supported ad types.

The following snippet demonstrates how to create a responsive search ad:

  let 
  
 adOperation 
  
 = 
  
 adGroup 
 . 
 newAd 
 (). 
 responsiveSearchAdBuilder 
 () 
  
 . 
 withHeadlines 
 ([ 
 "Headline 1" 
 , 
  
 "Headline 2" 
 , 
  
 "Headline 3" 
 ]) 
  
 . 
 withDescriptions 
 ([ 
 "Description 1" 
 , 
  
 "Description 2" 
 ]) 
  
 . 
 withFinalUrl 
 ( 
 "http://www.example.com" 
 ) 
  
 . 
 withPath1 
 ( 
 "path1" 
 ) 
  
 . 
 withPath2 
 ( 
 "path2" 
 ) 
  
 . 
 build 
 ();

Inspection

Some information associated with all ad types is immediately available from an Ad , such as an ad's ID and approval status. Additionally, any ad can be paused, enabled, or removed.

To access fields specific to an ad's type, such as a responsive search ad's headlines, use the asType() method to create an AdViewSpace . This provides access to an extended version of the Ad that exposes type-specific methods.

The following snippet gets the headlines of every responsive search ad:

  const 
  
 iterator 
  
 = 
  
 AdsApp 
 . 
 ads 
 (). 
 withCondition 
 ( 
 "Type = RESPONSIVE_SEARCH_AD" 
 ). 
 get 
 (); 
 while 
  
 ( 
 iterator 
 . 
 hasNext 
 ()) 
  
 { 
  
 let 
  
 ad 
  
 = 
  
 iterator 
 . 
 next 
 (); 
  
 let 
  
 responsiveSearchAd 
  
 = 
  
 ad 
 . 
 asType 
 (). 
 responsiveSearchAd 
 (); 
  
 let 
  
 headlines 
  
 = 
  
 responsiveSearchAd 
 . 
 getHeadlines 
 (); 
 }

Notice that the condition Type = RESPONSIVE_SEARCH_AD ensures every ad from the iterator is a responsive search ad. Attempting to view an ad with an incorrect type will result in an error that stops your script's execution, so it's important to view type-specific fields only when an ad's type is known.

The following snippet shows how to determine if an ad is the correct type using the Ad.isType() method:

  if 
  
 ( 
 ad 
 . 
 isType 
 (). 
 responsiveSearchAd 
 ()) 
  
 { 
  
 let 
  
 responsiveSearchAd 
  
 = 
  
 ad 
 . 
 asType 
 (). 
 responsiveSearchAd 
 (); 
  
 let 
  
 headlines 
  
 = 
  
 responsiveSearchAd 
 . 
 getHeadlines 
 (); 
  
 let 
  
 descriptions 
  
 = 
  
 responsiveSearchAd 
 . 
 getDescriptions 
 (); 
 }

While you cannot filter ads by headline text using standard selectors, you can filter them in JavaScript after retrieving them:

  const 
  
 iterator 
  
 = 
  
 AdsApp 
 . 
 ads 
 (). 
 withCondition 
 ( 
 "Type = RESPONSIVE_SEARCH_AD" 
 ). 
 get 
 (); 
 while 
  
 ( 
 iterator 
 . 
 hasNext 
 ()) 
  
 { 
  
 let 
  
 ad 
  
 = 
  
 iterator 
 . 
 next 
 (); 
  
 let 
  
 responsiveSearchAd 
  
 = 
  
 ad 
 . 
 asType 
 (). 
 responsiveSearchAd 
 (); 
  
 let 
  
 headlines 
  
 = 
  
 responsiveSearchAd 
 . 
 getHeadlines 
 (); 
  
 // Filter for ads containing a specific headline. 
  
 if 
  
 ( 
 headlines 
 . 
 some 
 ( 
 h 
  
 = 
>  
 h 
 . 
 getText 
 (). 
 includes 
 ( 
 "Special Offer" 
 ))) 
  
 { 
  
 console 
 . 
 log 
 ( 
 `Found ad with ID 
 ${ 
 ad 
 . 
 getId 
 () 
 } 
 ` 
 ); 
  
 } 
 }

Reporting

The ad_group_ad view can be used to query ad fields in addition to regular stats. For example, you can filter on ad type using ad_group_ad.ad.type . The following snippet shows how to retrieve the stats for all responsive search ads:

  const 
  
 results 
  
 = 
  
 AdsApp 
 . 
 search 
 ( 
  
 "SELECT ad_group_ad.ad_group.id, " 
  
 + 
  
 "ad_group_ad.ad.id, " 
  
 + 
  
 "metrics.clicks, " 
  
 + 
  
 "metrics.impressions, " 
  
 + 
  
 "metrics.cost " 
  
 + 
  
 "FROM ad_group_ad " 
  
 + 
  
 "WHERE ad_group_ad.ad.type = 'RESPONSIVE_SEARCH_AD' " 
  
 + 
  
 "AND segments.date DURING LAST_7_DAYS" 
 ); 
 while 
  
 ( 
 results 
 . 
 hasNext 
 ()) 
  
 { 
  
 let 
  
 row 
  
 = 
  
 results 
 . 
 next 
 (); 
  
 let 
  
 adId 
  
 = 
  
 row 
 . 
 adGroupAd 
 . 
 ad 
 . 
 id 
 ; 
  
 let 
  
 clicks 
  
 = 
  
 row 
 . 
 metrics 
 . 
 clicks 
 ; 
  
 ... 
 }

Filtering by asset content

To filter responsive search ads by the content of their headlines or descriptions at scale, use the ad_group_ad_asset_view resource. This view treats each headline and description as a separate row, allowing you to filter on the asset's text.

The following snippet retrieves stats for all responsive search ads that contain a specific headline:

  const 
  
 results 
  
 = 
  
 AdsApp 
 . 
 search 
 ( 
  
 "SELECT ad_group_ad.ad.id, " 
  
 + 
  
 "asset.text_asset.text, " 
  
 + 
  
 "metrics.clicks, " 
  
 + 
  
 "metrics.impressions " 
  
 + 
  
 "FROM ad_group_ad_asset_view " 
  
 + 
  
 "WHERE asset.text_asset.text LIKE '%Special Offer%' " 
  
 + 
  
 "AND ad_group_ad_asset_view.field_type = 'HEADLINE'" 
 ); 
 while 
  
 ( 
 results 
 . 
 hasNext 
 ()) 
  
 { 
  
 let 
  
 row 
  
 = 
  
 results 
 . 
 next 
 (); 
  
 let 
  
 adId 
  
 = 
  
 row 
 . 
 adGroupAd 
 . 
 ad 
 . 
 id 
 ; 
  
 let 
  
 text 
  
 = 
  
 row 
 . 
 asset 
 . 
 textAsset 
 . 
 text 
 ; 
  
 let 
  
 clicks 
  
 = 
  
 row 
 . 
 metrics 
 . 
 clicks 
 ; 
  
 console 
 . 
 log 
 ( 
 `Ad ID 
 ${ 
 adId 
 } 
 with headline " 
 ${ 
 text 
 } 
 " had 
 ${ 
 clicks 
 } 
 clicks.` 
 ); 
 }

See the reports guide for more information on reporting in scripts.