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

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

    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.
    Create a Mobile Website
    View Site in Mobile | Classic
    Share by: