AdsApp

Root object of Google Ads scripts API. Exposes methods for
  • Fetching Google Ads entities
  • Querying Google Ads reports
  • Accessing information about the state of the current execution

Methods:

MemberTypeDescription
adAssets AdsApp.AdAssets Returns the Google Ads asset interface.
adCustomizerSources AdsApp.AdCustomizerSourceSelector Returns the selector of all ad customizer data sources in the account.
adGroupTargeting AdsApp.AccountAdGroupTargeting Provides access to ad group-level targeting criteria, currently just audiences.
adGroups AdsApp.AdGroupSelector Returns the selector of all ad groups in the account.
adMedia AdsApp.AdMedia Returns the Google Ads media interface.
adParams AdsApp.AdParamSelector Returns the selector of all ad params in the account.
ads AdsApp.AdSelector Returns the selector of all ads in the account.
biddingStrategies AdsApp.BiddingStrategySelector Returns the selector of all flexible bidding strategies in the account.
budgetOrders AdsApp.BudgetOrderSelector Returns the selector of all budget orders in the account.
budgets AdsApp.BudgetSelector Returns the selector of all budgets in the account.
bulkUploads AdsApp.BulkUploads Provides access to bulk uploads: FileUpload, CsvUpload.
campaigns AdsApp.CampaignSelector Returns the selector of all campaigns in the account.
createLabel void Creates a new Label.
currentAccount AdsApp.Account Returns miscellaneous information about the Google Ads account in which the script is currently running.
display AdsApp.Display Provides access to display criteria that have been added to this account: Audience, DisplayKeyword, Placement, Topic.
drafts AdsApp.DraftSelector Returns the selector of all drafts in the account.
excludedPlacementLists AdsApp.ExcludedPlacementListSelector Returns a selector of all excluded placement lists in this account.
experiments AdsApp.ExperimentSelector Returns the selector of all experiments in the account.
extensions AdsApp.Extensions Provides access to ad extensions that have been added to this account: Callout, MobileApp, PhoneNumber, Price, Sitelink, and Snippet.
getExecutionInfo AdsApp.ExecutionInfo Returns miscellaneous information about the current script execution.
keywords AdsApp.KeywordSelector Returns the selector of all keywords in the account.
labels AdsApp.LabelSelector Returns the selector of all labels in the account.
mutate AdsApp.MutateResult Executes a Google Ads mutate.
mutateAll AdsApp.MutateResult[] Executes multiple Google Ads mutates.
negativeKeywordLists AdsApp.NegativeKeywordListSelector Returns a selector of all negative keyword lists in this account.
newAdCustomizerSourceBuilder AdsApp.AdCustomizerSourceBuilder Returns a new ad customizer source builder for this account.
newExcludedPlacementListBuilder AdsApp.ExcludedPlacementListBuilder Returns a new excluded placement list builder for this account.
newExperimentBuilder AdsApp.ExperimentBuilder Returns the builder for creating an experiment.
newNegativeKeywordListBuilder AdsApp.NegativeKeywordListBuilder Returns a new negative keyword list builder for this account.
performanceMaxCampaigns AdsApp.PerformanceMaxCampaignSelector Returns the selector of all performance max campaigns in the account.
productAds AdsApp.ProductAdSelector Returns the selector of all product ads in the account.
productGroups AdsApp.ProductGroupSelector Returns the selector of all product groups in the account.
recommendations AdsApp.RecommendationSelector Returns the selector of all recommendations in the account.
report AdsApp.Report Fetches a Google Ads report.
search AdsApp.SearchRowIterator Executes a Google Ads Search.
shoppingAdGroupTargeting AdsApp.AccountShoppingAdGroupTargeting Provides access to shopping ad group-level targeting criteria, currently just audiences.
shoppingAdGroups AdsApp.ShoppingAdGroupSelector Returns the selector of all shopping ad groups in the account.
shoppingCampaignTargeting AdsApp.AccountShoppingCampaignTargeting Provides access to shopping campaign-level targeting criteria, currently just audiences.
shoppingCampaigns AdsApp.ShoppingCampaignSelector Returns the selector of all shopping campaigns in the account.
targeting AdsApp.Targeting Provides access to campaign-level targeting criteria: device targeting, ad scheduling, location targeting, and audiences.
userlists AdsApp.UserListSelector Returns the selector of all user lists in the account.
videoAdGroups AdsApp.VideoAdGroupSelector Returns the selector of all video ad groups in the account.
videoAds AdsApp.VideoAdSelector Returns the selector of all video ads in the account.
videoCampaigns AdsApp.VideoCampaignSelector Returns the selector of all video campaigns in the account.
videoTargeting AdsApp.VideoTargeting Provides access to video criteria that have been added to this account: VideoAge, VideoAudience, VideoGender, VideoKeyword, VideoMobileAppCategory VideoMobileApplication, VideoParentalStatus, VideoPlacement, VideoTopic, VideoYouTubeChannel, VideoYouTubeVideo.

adAssets()

Returns the Google Ads asset interface. This supports selecting assets and building new assets.

Return values:

TypeDescription
AdsApp.AdAssets The ad asset interface.

adCustomizerSources()

Returns the selector of all ad customizer data sources in the account.

Return values:

TypeDescription
AdsApp.AdCustomizerSourceSelector The selector of all ad customizer data sources in the account.

adGroupTargeting()

Provides access to ad group-level targeting criteria, currently just audiences.

Return values:

TypeDescription
AdsApp.AccountAdGroupTargeting Access to ad group-level targeting criteria.

adGroups()

Returns the selector of all ad groups in the account.

Return values:

TypeDescription
AdsApp.AdGroupSelector The selector of all ad groups in the account.

adMedia()

Returns the Google Ads media interface. This supports uploading and fetching media objects.

Return values:

TypeDescription
AdsApp.AdMedia The ad media interface.

adParams()

Returns the selector of all ad params in the account.

Return values:

TypeDescription
AdsApp.AdParamSelector The selector of all ad params in the account.

ads()

Returns the selector of all ads in the account.

Return values:

TypeDescription
AdsApp.AdSelector The selector of all ads in the account.

biddingStrategies()

Returns the selector of all flexible bidding strategies in the account.

Return values:

TypeDescription
AdsApp.BiddingStrategySelector The selector of all flexible bidding strategies in the account.

budgetOrders()

Returns the selector of all budget orders in the account.

Return values:

TypeDescription
AdsApp.BudgetOrderSelector The selector of all budget orders in the account.

budgets()

Returns the selector of all budgets in the account.

Return values:

TypeDescription
AdsApp.BudgetSelector The selector of all budgets in the account.

bulkUploads()

Provides access to bulk uploads: FileUpload, CsvUpload.

Return values:

TypeDescription
AdsApp.BulkUploads Access to bulk uploads.

campaigns()

Returns the selector of all campaigns in the account.
var campaignSelector = AdsApp.campaigns();

Return values:

TypeDescription
AdsApp.CampaignSelector The selector of all campaigns in the account.

createLabel(name, description, backgroundColor)

Creates a new Label. You must always specify a name, but description and color are optional.

Note that you cannot create more than 100,000 labels per account.

Usage examples:

AdsApp.createLabel("My Label");

AdsApp.createLabel(
  "Modified by script", "These ads have been modified by a script");

AdsApp.createLabel(
  "Bad Keywords", "These keywords are performing poorly", "red");
You must specify optional arguments in order, i.e. you cannot specify color without the description.
// CORRECT: This will set the color to '#0088FF':
AdsApp.createLabel("Good", "", "#0088FF");

// WRONG: This will set the description to '#0088FF':
AdsApp.createLabel("Bad", "#0088FF");

Returns nothing.

Arguments:

NameTypeDescription
name String The name of the new Label. Label names are case sensitive and must be unique. Max length is 100 characters. Any leading or trailing white spaces will be trimmed.
description String Optional. The description of the new label. If not specified, the description will be empty. Max length is 200 characters.
backgroundColor String Optional. The background color of the new label. The color must be specified in either RGB form (#RRGGBB or #RGB), or one of the 16 basic CSS color names. If not specified, the new label will assume an arbitrary background color.

currentAccount()

Returns miscellaneous information about the Google Ads account in which the script is currently running.

Return values:

TypeDescription
AdsApp.Account Miscellaneous information about the Google Ads account in which the script is currently running.

display()

Provides access to display criteria that have been added to this account: Audience, DisplayKeyword, Placement, Topic.

Return values:

TypeDescription
AdsApp.Display Access to the display criteria that have been added to this account.

drafts()

Returns the selector of all drafts in the account.

Return values:

TypeDescription
AdsApp.DraftSelector The selector of all drafts in the account.

excludedPlacementLists()

Returns a selector of all excluded placement lists in this account.

Return values:

TypeDescription
AdsApp.ExcludedPlacementListSelector A selector of all excluded placement lists in this account.

experiments()

Returns the selector of all experiments in the account.

Return values:

TypeDescription
AdsApp.ExperimentSelector The selector of all experiments in the account.

extensions()

Provides access to ad extensions that have been added to this account: Callout, MobileApp, PhoneNumber, Price, Sitelink, and Snippet.

Return values:

TypeDescription
AdsApp.Extensions Access to ad extensions that have been added to this account.

getExecutionInfo()

Returns miscellaneous information about the current script execution.

Return values:

TypeDescription
AdsApp.ExecutionInfo Miscellaneous information about the current script execution.

keywords()

Returns the selector of all keywords in the account.

Return values:

TypeDescription
AdsApp.KeywordSelector The selector of all keywords in the account.

labels()

Returns the selector of all labels in the account.

Return values:

TypeDescription
AdsApp.LabelSelector The selector of all labels in the account.

mutate(operation, optArgs)

Executes a Google Ads mutate.

The operation argument is a MutateOperation as defined in the Google Ads API REST Interface.

Example usages:

const customerId = AdsApp.currentAccount().getCustomerId();
const campaignId = 12345;

const createAdGroupResponse = AdsApp.mutate(
  {
    adGroupOperation: {
      create: {
        campaign: `customers/${customerId}/campaigns/${campaignId}`,
        name: 'My Ad Group Name',
        cpcBidMicros: '1230000' // $1.23 in micros
      }
    }
  });
const keywordText = 'Example Text';
const finalUrl = 'https://example.final.url.com/';
const createKeywordResponse = AdsApp.mutate(
  {
    adGroupCriterionOperation: {
      create: {
        adGroup: createAdGroupResponse.getResourceName(),
        keyword: {
          matchType: 'BROAD',
          text: keywordText
        },
        finalUrls: [ finalUrl ]
      }
    }
  });

This method also accepts an optional arguments object. The following fields are supported:

NameTypeDescription
apiVersion String The Google Ads API version to query. Sunsetted versions are not allowed. Defaults to the most recent supported version.

Arguments:

NameTypeDescription
operation Object The Google Ads API mutate operation.
optArgs Object Optional arguments.

Return values:

TypeDescription
AdsApp.MutateResult The result of the mutate.

mutateAll(operations, optArgs)

Executes multiple Google Ads mutates.

The operations argument is an array of MutateOperation objects as defined in the Google Ads API REST Interface.

Example usages:

const customerId = AdsApp.currentAccount().getCustomerId();
const campaignId = 12345;
const keywordText = 'Example Text';
const finalUrl = 'https://example.final.url.com/';

const mutateResponses = AdsApp.mutateAll([
  {
    adGroupOperation: {
      create: {
        resourceName: `customers/${customerId}/adGroups/-1`
        campaign: `customers/${customerId}/campaigns/${campaignId}`,
        name: 'My Ad Group Name',
        cpcBidMicros: '1230000' // $1.23 in micros
      }
    }
  },
  {
    adGroupCriterionOperation: {
      create: {
        adGroup: `customers/${customerId}/adGroups/-1`,
        keyword: {
          matchType: 'BROAD',
          text: keywordText
        },
        finalUrls: [ finalUrl ]
      }
    }
  }]);

This method also accepts an optional arguments object. The following fields are supported:

NameTypeDescription
apiVersion String The Google Ads API version to query. Sunsetted versions are not allowed. Defaults to the most recent supported version.
partialFailure boolean If false, then all operations either succeed together, or all fail. If true, then some operations may succeed while others fail.

Arguments:

NameTypeDescription
operations Object[] The Google Ads API mutate operations.
optArgs Object Optional arguments.

Return values:

TypeDescription
AdsApp.MutateResult[] The results of the mutates.

negativeKeywordLists()

Returns a selector of all negative keyword lists in this account.

Return values:

TypeDescription
AdsApp.NegativeKeywordListSelector A selector of all negative keyword lists in this account.

newAdCustomizerSourceBuilder()

Returns a new ad customizer source builder for this account. Once AdCustomizerSourceBuilder.build() is called, the ad customizer source will be created in this account.

Return values:

TypeDescription
AdsApp.AdCustomizerSourceBuilder Ad customizer source builder used to create a new ad customizer data source in the account.

newExcludedPlacementListBuilder()

Returns a new excluded placement list builder for this account. Once builder.build() is called, the new excluded placement list will be created in this account.

Return values:

TypeDescription
AdsApp.ExcludedPlacementListBuilder The excluded placement list builder used to create a new excluded placement list in this account.

newExperimentBuilder()

Returns the builder for creating an experiment.

Return values:

TypeDescription
AdsApp.ExperimentBuilder The builder for creating an experiment in the account.

newNegativeKeywordListBuilder()

Returns a new negative keyword list builder for this account. Once builder.build() is called, the new negative keyword list will be created in this account.

Return values:

TypeDescription
AdsApp.NegativeKeywordListBuilder The negative keyword list builder used to create a new negative keyword list in this account.

performanceMaxCampaigns()

Returns the selector of all performance max campaigns in the account.

Return values:

TypeDescription
AdsApp.PerformanceMaxCampaignSelector The selector of all performance max campaigns in the account.

productAds()

Returns the selector of all product ads in the account.

Return values:

TypeDescription
AdsApp.ProductAdSelector The selector of all product ads in the account.

productGroups()

Returns the selector of all product groups in the account.

Return values:

TypeDescription
AdsApp.ProductGroupSelector The selector of all product groups in the account.

recommendations()

Returns the selector of all recommendations in the account.

Return values:

TypeDescription
AdsApp.RecommendationSelector The selector of all recommendations in the account.

report(query, optArgs)

Fetches a Google Ads report.

Example usages:

var report1 = AdsApp.report(
    'SELECT search_term_view.search_term, metrics.ctr ' +
    'FROM   search_term_view ' +
    'WHERE  segments.date BETWEEN "2013-01-01" AND "2013-03-01"');

var report2 = AdsApp.report(
    'SELECT ad_group.id, ad_group_criterion.criterion_id, ' +
    '       ad_group_criterion.keyword.text, metrics.impressions, ' +
    '       metrics.clicks ' +
    'FROM   keyword_view ' +
    'WHERE  segments.date BETWEEN "2013-01-01" AND "2013-03-01"', {
      apiVersion: 'v17'
    });

var report3 = AdsApp.report(
    'SELECT ad_group.id, ad_group_criterion.criterion_id, ' +
    '       ad_group_criterion.keyword.text, ' +
    '       campaign.name, metrics.impressions, metrics.clicks ' +
    'FROM   keyword_view ' +
    'WHERE  segments.date BETWEEN "2013-01-01" AND "2013-03-01"', {
      apiVersion: 'v17'
    });

Reports are specified through a GAQL query. For GAQL details, see the GAQL guide and the list of accessible resources and fields.

This method also accepts an optional arguments object. The following optional arguments are supported:

NameTypeDescription
includeZeroImpressions boolean Whether or not to include entities that had zero impressions in the report. This field is not allowed when the query uses GAQL. See here for details on how GAQL handles zero impressions. Defaults to true for AWQL queries.
returnMoneyInMicros boolean Whether or not to represent money in micros ('1370000') or in currency ('1.37'). This field is not allowed when the query uses GAQL. In that case, all money values are represented in micros. Defaults to false for AWQL queries.
apiVersion String For GAQL queries, the Google Ads API version to query. Sunsetted versions for GAQL queries are not allowed.
resolveGeoNames boolean Whether or not to convert Geo CriteriaIds (e.g. CountryCriteriaId and CityCriteriaId) into names (e.g. 'United States' and 'San Francisco'). Set to true if you want names. Set to false if you want numerical IDs. Defaults to true.

Arguments:

NameTypeDescription
query String AWQL or GAQL query specifying the report.
optArgs Object Optional arguments.

Return values:

TypeDescription
AdsApp.Report The requested report.

search(query, optArgs)

Executes a Google Ads Search.

Example usages:

var search1 = AdsApp.search(
    'SELECT search_term_view.search_term, metrics.ctr ' +
    'FROM   search_term_view ' +
    'WHERE  segments.date BETWEEN "2013-01-01" AND "2013-03-01"');

var search2 = AdsApp.search(
    'SELECT ad_group.id, ad_group_criterion.criterion_id, ' +
    ' ad_group_criterion.keyword.text, campaign.name, ' +
    ' metrics.impressions, metrics.clicks ' +
    'FROM keyword_view ' +
    'WHERE segments.date BETWEEN ' +
    ' "2013-01-01" AND "2013-03-01"', {
      apiVersion: 'v17'
    });

Searches are specified via a GAQL query. For detailed information, please see the GAQL guide and the list of resources and fields.

This method also accepts an optional arguments object. Currently, there is only one supported field:

NameTypeDescription
apiVersion String The Google Ads API version to query. Sunsetted versions are not allowed. Defaults to the most recent supported version.

Arguments:

NameTypeDescription
query String GAQL search query.
optArgs Object Optional arguments.

Return values:

TypeDescription
AdsApp.SearchRowIterator The requested report.

shoppingAdGroupTargeting()

Provides access to shopping ad group-level targeting criteria, currently just audiences.

Return values:

TypeDescription
AdsApp.AccountShoppingAdGroupTargeting Access to shopping ad group-level targeting criteria.

shoppingAdGroups()

Returns the selector of all shopping ad groups in the account.

Return values:

TypeDescription
AdsApp.ShoppingAdGroupSelector The selector of all shopping ad groups in the account.

shoppingCampaignTargeting()

Provides access to shopping campaign-level targeting criteria, currently just audiences.

Return values:

TypeDescription
AdsApp.AccountShoppingCampaignTargeting Access to shopping campaign-level targeting criteria.

shoppingCampaigns()

Returns the selector of all shopping campaigns in the account.

Return values:

TypeDescription
AdsApp.ShoppingCampaignSelector The selector of all shopping campaigns in the account.

targeting()

Provides access to campaign-level targeting criteria: device targeting, ad scheduling, location targeting, and audiences.

Return values:

TypeDescription
AdsApp.Targeting Access to campaign-level targeting criteria.

userlists()

Returns the selector of all user lists in the account.

Return values:

TypeDescription
AdsApp.UserListSelector The selector of all user lists in the account.

videoAdGroups()

Returns the selector of all video ad groups in the account.

Return values:

TypeDescription
AdsApp.VideoAdGroupSelector The selector of all video ad groups in the account.

videoAds()

Returns the selector of all video ads in the account.

Return values:

TypeDescription
AdsApp.VideoAdSelector The selector of all video ads in the account.

videoCampaigns()

Returns the selector of all video campaigns in the account.

Return values:

TypeDescription
AdsApp.VideoCampaignSelector The selector of all video campaigns in the account.

videoTargeting()

Provides access to video criteria that have been added to this account: VideoAge, VideoAudience, VideoGender, VideoKeyword, VideoMobileAppCategory VideoMobileApplication, VideoParentalStatus, VideoPlacement, VideoTopic, VideoYouTubeChannel, VideoYouTubeVideo.

Return values:

TypeDescription
AdsApp.VideoTargeting Access to the video criteria that have been added to this account.