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:

Member	Type	Description
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:

Type	Description
AdsApp.AdAssets	The ad asset interface.

adCustomizerSources()

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

Return values:

Type	Description
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:

Type	Description
AdsApp.AccountAdGroupTargeting	Access to ad group-level targeting criteria.

adGroups()

Returns the selector of all ad groups in the account.

Return values:

Type	Description
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:

Type	Description
AdsApp.AdMedia	The ad media interface.

adParams()

Returns the selector of all ad params in the account.

Return values:

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

ads()

Returns the selector of all ads in the account.

Return values:

Type	Description
AdsApp.AdSelector	The selector of all ads in the account.

biddingStrategies()

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

Return values:

Type	Description
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:

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

budgets()

Returns the selector of all budgets in the account.

Return values:

Type	Description
AdsApp.BudgetSelector	The selector of all budgets in the account.

bulkUploads()

Provides access to bulk uploads: FileUpload, CsvUpload.

Return values:

Type	Description
AdsApp.BulkUploads	Access to bulk uploads.

campaigns()

Returns the selector of all campaigns in the account.

var campaignSelector = AdsApp.campaigns();

Return values:

Type	Description
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:

Name	Type	Description
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:

Type	Description
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:

Type	Description
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:

Type	Description
AdsApp.DraftSelector	The selector of all drafts in the account.

excludedPlacementLists()

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

Return values:

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

experiments()

Returns the selector of all experiments in the account.

Return values:

Type	Description
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:

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

getExecutionInfo()

Returns miscellaneous information about the current script execution.

Return values:

Type	Description
AdsApp.ExecutionInfo	Miscellaneous information about the current script execution.

keywords()

Returns the selector of all keywords in the account.

Return values:

Type	Description
AdsApp.KeywordSelector	The selector of all keywords in the account.

labels()

Returns the selector of all labels in the account.

Return values:

Type	Description
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:

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

Arguments:

Name	Type	Description
operation	Object	The Google Ads API mutate operation.
optArgs	Object	Optional arguments.

Return values:

Type	Description
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:

Name	Type	Description
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:

Name	Type	Description
operations	Object[]	The Google Ads API mutate operations.
optArgs	Object	Optional arguments.

Return values:

Type	Description
AdsApp.MutateResult[]	The results of the mutates.

negativeKeywordLists()

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

Return values:

Type	Description
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:

Type	Description
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:

Type	Description
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:

Type	Description
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:

Type	Description
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:

Type	Description
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:

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

productGroups()

Returns the selector of all product groups in the account.

Return values:

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

recommendations()

Returns the selector of all recommendations in the account.

Return values:

Type	Description
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: 'v18'
    });

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: 'v18'
    });

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:

Name	Type	Description
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:

Name	Type	Description
query	String	AWQL or GAQL query specifying the report.
optArgs	Object	Optional arguments.

Return values:

Type	Description
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: 'v18'
    });

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:

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

Arguments:

Name	Type	Description
query	String	GAQL search query.
optArgs	Object	Optional arguments.

Return values:

Type	Description
AdsApp.SearchRowIterator	The requested report.

shoppingAdGroupTargeting()

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

Return values:

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

shoppingAdGroups()

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

Return values:

Type	Description
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:

Type	Description
AdsApp.AccountShoppingCampaignTargeting	Access to shopping campaign-level targeting criteria.

shoppingCampaigns()

Returns the selector of all shopping campaigns in the account.

Return values:

Type	Description
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:

Type	Description
AdsApp.Targeting	Access to campaign-level targeting criteria.

userlists()

Returns the selector of all user lists in the account.

Return values:

Type	Description
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:

Type	Description
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:

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

videoCampaigns()

Returns the selector of all video campaigns in the account.

Return values:

Type	Description
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:

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