This is the legacy documentation for Google Ads scripts. Go to the current docs.

Ads

Add an expanded text ad

function addExpandedTextAd() {
  // If you have multiple adGroups with the same name, this snippet will
  // pick an arbitrary matching ad group each time. In such cases, just
  // filter on the campaign name as well:
  //
  // AdsApp.adGroups()
  //     .withCondition('Name = "INSERT_ADGROUP_NAME_HERE"')
  //     .withCondition('CampaignName = "INSERT_CAMPAIGN_NAME_HERE"')
  var adGroupIterator = AdsApp.adGroups()
      .withCondition('Name = "INSERT_ADGROUP_NAME_HERE"')
      .get();
  if (adGroupIterator.hasNext()) {
    var adGroup = adGroupIterator.next();
    adGroup.newAd().expandedTextAdBuilder()
        .withHeadlinePart1('First headline of ad')
        .withHeadlinePart2('Second headline of ad')
        .withDescription('Ad description')
        .withPath1('path1')
        .withPath2('path2')
        .withFinalUrl('http://www.example.com')
        .build();
    // ExpandedTextAdBuilder has additional options.
    // For more details, see
    // https://developers.google.com/google-ads/scripts-legacy/docs/reference/adsapp/adsapp_expandedtextadbuilder
  }
}

Add an image ad

function addImageAd() {
  // If you have multiple adGroups with the same name, this snippet will
  // pick an arbitrary matching ad group each time. In such cases, just
  // filter on the campaign name as well:
  //
  // AdsApp.adGroups()
  //     .withCondition('Name = "INSERT_ADGROUP_NAME_HERE"')
  //     .withCondition('CampaignName = "INSERT_CAMPAIGN_NAME_HERE"')
  var adGroupIterator = AdsApp.adGroups()
      .withCondition('Name = "INSERT_ADGROUP_NAME_HERE"')
      .get();
  var mediaIterator = AdsApp.adMedia().media()
      .withCondition('Name = "INSERT_IMAGE_NAME_HERE"')
      .get();
  if (adGroupIterator.hasNext() && mediaIterator.hasNext()) {
    var adGroup = adGroupIterator.next();
    var image = mediaIterator.next();
    adGroup.newAd().imageAdBuilder()
        .withName('Ad name')
        .withImage(image)
        .withDisplayUrl('http://www.example.com')
        .withFinalUrl('http://www.example.com')
        .build();
    // ImageAdBuilder has additional options.
    // For more details, see
    // https://developers.google.com/google-ads/scripts-legacy/docs/reference/adsapp/adsapp_imageadbuilder
  }
}

Add an HTML5 ad

function addHtml5Ad() {
  // If you have multiple adGroups with the same name, this snippet will
  // pick an arbitrary matching ad group each time. In such cases, just
  // filter on the campaign name as well:
  //
  // AdsApp.adGroups()
  //     .withCondition('Name = "INSERT_ADGROUP_NAME_HERE"')
  //     .withCondition('CampaignName = "INSERT_CAMPAIGN_NAME_HERE"')
  var adGroupIterator = AdsApp.adGroups()
      .withCondition('Name = "INSERT_ADGROUP_NAME_HERE"')
      .get();
  var mediaIterator = AdsApp.adMedia().media()
      .withCondition('Name = "INSERT_MEDIA_BUNDLE_NAME_HERE"')
      .get();
  if (adGroupIterator.hasNext() && mediaIterator.hasNext()) {
    var adGroup = adGroupIterator.next();
    var mediaBundle = mediaIterator.next();
    adGroup.newAd().html5AdBuilder()
        .withName('Ad name')
        .withMediaBundle(mediaBundle)
        .withEntryPoint('someDirectory/index.html')
        .withDimensions('300x250')
        .withDisplayUrl('http://www.example.com')
        .withFinalUrl('http://www.example.com')
        .build();
    // HTML5AdBuilder has additional options.
    // For more details, see
    // https://developers.google.com/google-ads/scripts-legacy/docs/reference/adsapp/adsapp_html5adbuilder
  }
}

Add a Gmail image ad

function addGmailImageAd() {
  // If you have multiple adGroups with the same name, this snippet will
  // pick an arbitrary matching ad group each time. In such cases, just
  // filter on the campaign name as well:
  //
  // AdsApp.adGroups()
  //     .withCondition('Name = "INSERT_ADGROUP_NAME_HERE"')
  //     .withCondition('CampaignName = "INSERT_CAMPAIGN_NAME_HERE"')
  var adGroupIterator = AdsApp.adGroups()
      .withCondition('Name = "INSERT_ADGROUP_NAME_HERE"')
      .get();
  var logoMediaIterator = AdsApp.adMedia().media()
      .withCondition('Name = "INSERT_LOGO_IMAGE_NAME_HERE"')
      .get();
  var imageMediaIterator = AdsApp.adMedia().media()
      .withCondition('Name = "INSERT_IMAGE_NAME_HERE"')
      .get();
  if (adGroupIterator.hasNext() &&
      logoMediaIterator.hasNext() &&
      imageMediaIterator.hasNext()) {
    var adGroup = adGroupIterator.next();
    var logo = logoMediaIterator.next();
    var image = imageMediaIterator.next();
    adGroup.newAd().gmailImageAdBuilder()
        .withName('Ad name')
        .withAdvertiser('Advertiser')
        .withSubject('Subject')
        .withDescription('Description')
        .withLogo(logo)
        .withImage(image)
        .withFinalUrl('http://www.example.com')
        .withDisplayUrl('http://www.example.com')
        .build();
    // GmailImageAdBuilder has additional options.
    // For more details, see
    // https://developers.google.com/google-ads/scripts-legacy/docs/reference/adsapp/adsapp_gmailimageadbuilder
  }
}

Add a Gmail single promotion ad

function addGmailSinglePromotionAd() {
  // If you have multiple adGroups with the same name, this snippet will
  // pick an arbitrary matching ad group each time. In such cases, just
  // filter on the campaign name as well:
  //
  // AdsApp.adGroups()
  //     .withCondition('Name = "INSERT_ADGROUP_NAME_HERE"')
  //     .withCondition('CampaignName = "INSERT_CAMPAIGN_NAME_HERE"')
  var adGroupIterator = AdsApp.adGroups()
      .withCondition('Name = "INSERT_ADGROUP_NAME_HERE"')
      .get();
  var logoMediaIterator = AdsApp.adMedia().media()
      .withCondition('Name = "INSERT_LOGO_IMAGE_NAME_HERE"')
      .get();
  var imageMediaIterator = AdsApp.adMedia().media()
      .withCondition('Name = "INSERT_IMAGE_NAME_HERE"')
      .get();
  if (adGroupIterator.hasNext() &&
      logoMediaIterator.hasNext() &&
      imageMediaIterator.hasNext()) {
    var adGroup = adGroupIterator.next();
    var logo = logoMediaIterator.next();
    var image = imageMediaIterator.next();
    adGroup.newAd().gmailSinglePromotionAdBuilder()
        .withName('Ad name')
        .withContent('Content')
        .withHeadline('Headline')
        .withAdvertiser('Advertiser')
        .withSubject('Subject')
        .withDescription('Description')
        .withCallToAction('Call to action')
        .withLogo(logo)
        .withImage(image)
        .withFinalUrl('http://www.example.com')
        .withDisplayUrl('http://www.example.com')
        .build();
    // GmailSinglePromotionAdBuilder has additional options.
    // For more details, see
    // https://developers.google.com/google-ads/scripts-legacy/docs/reference/adsapp/adsapp_gmailsinglepromotionadbuilder
  }
}

Add a Gmail multi-product ad

function addGmailMultiProductAd() {
  // If you have multiple adGroups with the same name, this snippet will
  // pick an arbitrary matching ad group each time. In such cases, just
  // filter on the campaign name as well:
  //
  // AdsApp.adGroups()
  //     .withCondition('Name = "INSERT_ADGROUP_NAME_HERE"')
  //     .withCondition('CampaignName = "INSERT_CAMPAIGN_NAME_HERE"')
  var adGroupIterator = AdsApp.adGroups()
      .withCondition('Name = "INSERT_ADGROUP_NAME_HERE"')
      .get();
  var logoMediaIterator = AdsApp.adMedia().media()
      .withCondition('Name = "INSERT_LOGO_IMAGE_NAME_HERE"')
      .get();
  var itemImageMediaIterator = AdsApp.adMedia().media()
      .withCondition('Name = "INSERT_ITEM_1_IMAGE_NAME_HERE"')
      .get();
  if (adGroupIterator.hasNext() &&
      logoMediaIterator.hasNext() &&
      itemImageMediaIterator.hasNext()) {
    var adGroup = adGroupIterator.next();
    var logo = logoMediaIterator.next();
    var item1Image = itemImageMediaIterator.next();
    adGroup.newAd().gmailMultiProductAdBuilder()
        .withName('Ad name')
        .withAdvertiser('Advertiser')
        .withSubject('Subject')
        .withDescription('Description')
        .withHeadline('Headline')
        .withLogo(logo)
        .withItemImages([item1Image])
        .withItemTitles(['Item 1 title'])
        .withItemButtonCallsToAction(['Item 1 button text'])
        .withItemButtonFinalUrls(['http://www.example.com/item_1_button'])
        .withFinalUrl('http://www.example.com')
        .withDisplayUrl('http://www.example.com')
        .build();
    // GmailMultiProductAdBuilder has additional options.
    // For more details, see
    // https://developers.google.com/google-ads/scripts-legacy/docs/reference/adsapp/adsapp_gmailmultiproductadbuilder
  }
}

Add a responsive display ad

// You create responsive display ads in two steps:
//   1. Create or retrieve assets (marketing images, square marketing images,
//      optional logos, optional landscape logos, and optional YouTube videos)
//   2. Create the ad.
//
// The following function assumes you have not already created named assets.
function addResponsiveDisplayAd() {
  // If you have multiple adGroups with the same name, this snippet will
  // pick an arbitrary matching ad group each time. In such cases, just
  // filter on the campaign name as well:
  //
  // AdsApp.adGroups()
  //     .withCondition('Name = "INSERT_ADGROUP_NAME_HERE"')
  //     .withCondition('CampaignName = "INSERT_CAMPAIGN_NAME_HERE"')
  var adGroupIterator = AdsApp.adGroups()
      .withCondition('Name = "INSERT_ADGROUP_NAME_HERE"')
      .get();

  // If you have already created named image assets, select them like this:
  //
  // var marketingImages = [];
  // var marketingImageIterator = AdsApp.adAssets()
  //     .assets()
  //     .withCondition('Name IN ["INSERT_FIRST_ASSET_NAME_HERE",
  //                              "INSERT_SECOND_ASSET_NAME_HERE"]')
  //     .get();
  // while (marketingImageIterator.hasNext()) {
  //   marketingImages.push(marketingImageIterator.next());
  // }

  if (adGroupIterator.hasNext()) {
    var adGroup = adGroupIterator.next();
    var adGroupBuilder = adGroup.newAd()
        .responsiveDisplayAdBuilder()
        .withBusinessName('Your business name')
        .withFinalUrl('http://www.example.com')
        .withHeadlines(['First headline', 'Second headline'])
        .withDescriptions(
            ['First description', 'Second description', 'Third description']);

    // If you selected assets with a snippet as shown above, then provide those
    // assets here like this:
    //
    // adGroupBuilder = adGroupBuilder.withMarketingImages(marketingImages);

    adGroupBuilder
        .addMarketingImage(
            buildImageAsset("rectangular image asset", "https://goo.gl/3b9Wfh"))
        .addSquareMarketingImage(
            buildImageAsset("square image asset", "https://goo.gl/mtt54n"))
        .build();

    // ResponsiveDisplayAdBuilder has additional options.
    // For more details, see
    // https://developers.google.com/google-ads/scripts-legacy/docs/reference/adsapp/adsapp_responsivedisplayadbuilder
  }
}

function buildImageAsset(assetName, imageUrl) {
  var imageBlob = UrlFetchApp.fetch(imageUrl).getBlob();
  return AdsApp.adAssets().newImageAssetBuilder()
      .withData(imageBlob)
      .withName(assetName)
      .build()
      .getResult();
}

Pause ads in an ad group

function pauseAdsInAdGroup() {
  var adGroupIterator = AdsApp.adGroups()
      .withCondition('Name = "INSERT_ADGROUP_NAME_HERE"')
      .get();
  if (adGroupIterator.hasNext()) {
    var adGroup = adGroupIterator.next();
    var adsIterator = adGroup.ads().get();
    while (adsIterator.hasNext()) {
      var ad = adsIterator.next();
      ad.pause();
    }
  }
}

Get expanded text ads in an ad group

function getExpandedTextAdsInAdGroup() {
  var adGroupIterator = AdsApp.adGroups()
      .withCondition('Name = "INSERT_ADGROUP_NAME_HERE"')
      .get();
  if (adGroupIterator.hasNext()) {
    var adGroup = adGroupIterator.next();
    var adsIterator = adGroup.ads()
      .withCondition('Type=EXPANDED_TEXT_AD')
      .get();
    while (adsIterator.hasNext()) {
      var ad = adsIterator.next().asType().expandedTextAd();
      logExpandedTextAd(ad);
    }
  }
}

function logExpandedTextAd(expandedTextAd) {
  Logger.log('Headline part 1 : ' + expandedTextAd.getHeadlinePart1());
  Logger.log('Headline part 2 : ' + expandedTextAd.getHeadlinePart2());
  Logger.log('Description : ' + expandedTextAd.getDescription());
  Logger.log('Path 1 : ' + expandedTextAd.getPath1());
  Logger.log('Path 2 : ' + expandedTextAd.getPath2());
  Logger.log('Final URL : ' + expandedTextAd.urls().getFinalUrl());
  Logger.log('Mobile final URL : ' + expandedTextAd.urls().getFinalUrl());
  Logger.log('Final URL : ' + expandedTextAd.urls().getMobileFinalUrl());
  Logger.log('Tracking template : ' +
      expandedTextAd.urls().getTrackingTemplate());
  Logger.log('Custom parameters : ' +
      expandedTextAd.urls().getCustomParameters());
  Logger.log('Approval Status : ' +
      expandedTextAd.getApprovalStatus());
  Logger.log('Enabled : ' + expandedTextAd.isEnabled());
}

Get text ads in an ad group

function getTextAdsInAdGroup() {
  var adGroupIterator = AdsApp.adGroups()
      .withCondition('Name = "INSERT_ADGROUP_NAME_HERE"')
      .get();
  if (adGroupIterator.hasNext()) {
    var adGroup = adGroupIterator.next();
    // You can filter for ads of a particular type, using the AdType selector.
    // See https://developers.google.com/google-ads/scripts-legacy/docs/reference/adsapp/adsapp_adselector#withCondition_1
    // for possible values.

    var adsIterator = adGroup.ads().withCondition('Type=TEXT_AD').get();
    while (adsIterator.hasNext()) {
      var ad = adsIterator.next();
      logAd(ad);
    }
  }
}

function logAd(ad) {
  Logger.log('Headline : ' + ad.getHeadline());
  Logger.log('Line1 : ' + ad.getDescription1());
  Logger.log('Line2 : ' + ad.getDescription2());
  Logger.log('Final URL : ' + ad.urls().getFinalUrl());
  Logger.log('Display URL : ' + ad.getDisplayUrl());
  Logger.log('Approval Status : ' + ad.getApprovalStatus());
  Logger.log('Mobile preferred : ' + ad.isMobilePreferred());
  Logger.log('Enabled : ' + ad.isEnabled());
}

Get stats for ads in an ad group

function getAdStats() {
  var adGroupIterator = AdsApp.adGroups()
        .withCondition('Name = "INSERT_ADGROUP_NAME_HERE"')
        .get();
  if (adGroupIterator.hasNext()) {
    var adGroup = adGroupIterator.next();
    // If you want to restrict your search to some ads only, then you could
    // apply a label and retrieve ads as
    //
    //   var label = AdsApp.labels()
    //             .withCondition('Name="INSERT_LABEL_NAME_HERE"')
    //             .get()
    //             .next();
    //   var adsIterator = label.ads().get();

    var adsIterator = adGroup.ads().get();
    while (adsIterator.hasNext()) {
      var ad = adsIterator.next();
      // You can also request reports for pre-defined date ranges. See
      // https://developers.google.com/adwords/api/docs/guides/awql,
      // DateRangeLiteral section for possible values.
      var stats = ad.getStatsFor('LAST_MONTH');
      Logger.log(adGroup.getName() + ', ' +
          stats.getClicks() + ', ' + stats.getImpressions());
    }
  }
}

Get responsive display ads in an ad group

function getResponsiveDisplayAdsInAdGroup() {
  // Responsive display ads can include multiple text and multiple media assets
  // in the ad, while legacy responsive display ads cannot. Use a condition
  // 'Type = "MULTI_ASSET_RESPONSIVE_DISPLAY_AD"' to select the former and
  // condition 'Type = "LEGACY_RESPONSIVE_DISPLAY_AD"' to select the
  // latter. 'Type = "RESPONSIVE_DISPLAY_AD"' will also select legacy responsive
  // display ads, but the syntax is deprecated.
  //
  // When an ad iterator includes both responsive display ads and legacy
  // responsive display ads, use the ad.isLegacy() method to determine the style
  // of the ad.
  var adGroupIterator = AdsApp.adGroups()
      .withCondition('Name = "INSERT_ADGROUP_NAME_HERE"')
      .get();
  if (adGroupIterator.hasNext()) {
    var adGroup = adGroupIterator.next();
    var adsIterator = adGroup.ads()
        .withCondition('Type IN ["MULTI_ASSET_RESPONSIVE_DISPLAY_AD",
                                 "LEGACY_RESPONSIVE_DISPLAY_AD"]')
        .get();
    while (adsIterator.hasNext()) {
      var ad = adsIterator.next().asType().responsiveDisplayAd();
      if (ad.isLegacy()) {
        logLegacyResponsiveDisplayAd(ad);
      } else {
        logResponsiveDisplayAd(ad);
      }
    }
  }
}

function logLegacyResponsiveDisplayAd(ad) {
  Logger.log('Long headlines : ' + ad.getLongHeadline());
  Logger.log('Short headline : ' + ad.getShortHeadline());
  Logger.log('Description : ' + ad.getDescription());
  Logger.log('Business name : ' + ad.getBusinessName());
  Logger.log('Marketing image : ' + ad.getMarketingImage().getName());
  Logger.log('Logo image : ' + ad.getLogoImage().getName());
  Logger.log('Approval status : ' + ad.getApprovalStatus());
  Logger.log('Enabled : ' + ad.isEnabled());
}

function logResponsiveDisplayAd(ad) {
  Logger.log('Long headline : ' + ad.getLongHeadline());
  logTextAssets('Short headline ', ad.getHeadlines());
  logTextAssets('Description ', ad.getDescriptions());
  Logger.log('Business name : ' + ad.getBusinessName());
  logImageAssets('Marketing image ', ad.getMarketingImages());
  logImageAssets('Square marketing image ', ad.getSquareMarketingImages());
  logImageAssets('Logo image ', ad.getLogoImages());
  logImageAssets('Landscape logo image ', ad.getLandscapeLogoImages());
  logYouTubeAssets('YouTube video ', ad.getYouTubeVideos());
  Logger.log('Approval status : ' + ad.getApprovalStatus());
  Logger.log('Enabled : ' + ad.isEnabled());
}

function logTextAssets(prefix, assetArray) {
  for (var i = 0; i < assetArray.length; i++) {
    Logger.log(prefix + i + ' : ' + assetArray[i].text);
  }
}

function logImageAssets(prefix, assetArray) {
  for (var i = 0; i < assetArray.length; i++) {
    Logger.log(prefix + i + ' : ' + assetArray[i].getName());
  }
}

function logYouTubeAssets(prefix, assetArray) {
  for (var i = 0; i < assetArray.length; i++) {
    Logger.log(prefix + i + ' : ' + assetArray[i].getYouTubeVideoId());
  }
}