AdsApp

AI-generated Key Takeaways

• The Google Ads scripts API root object provides methods for fetching entities, querying reports, and accessing execution information.

• The API offers various methods to select entities like campaigns, ad groups, ads, keywords, and more.

• Functions are available to access and manage targeting criteria at campaign, ad group, and shopping levels.

• Methods for creating and managing labels, experiments, and negative keyword lists are included.

• The API supports fetching reports and executing search queries using AWQL or GAQL.

• There are methods for performing single or multiple Google Ads mutate operations via the Google Ads API REST Interface.

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.
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.
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 search and display campaigns in the account.
createLabel(name, description, backgroundColor)	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(operation, optArgs)	AdsApp.MutateResult	Executes a Google Ads mutate.
mutateAll(operations, optArgs)	AdsApp.MutateResult[]	Executes multiple Google Ads mutates.
negativeKeywordLists()	AdsApp.NegativeKeywordListSelector	Returns a selector of all negative keyword lists in 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(query, optArgs)	AdsApp.Report	Fetches a Google Ads report.
search(query, optArgs)	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.

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.

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 search and display campaigns in the account.

var campaignSelector = AdsApp.campaigns();

Return values:

Type	Description
AdsApp.CampaignSelector	The selector of all search and display 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.

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

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

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

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.