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,
Message, MobileApp, PhoneNumber, 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. |
| 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. |
| newNegativeKeywordListBuilder |
AdsApp.NegativeKeywordListBuilder |
Returns a new negative keyword list builder for this 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. |
| 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:
adCustomizerSources()
Returns the selector of all ad customizer data sources in the account.
Return values:
adGroupTargeting()
Provides access to ad group-level targeting criteria, currently just audiences.
Return values:
adGroups()
Returns the selector of all ad groups in the account.
Return values:
Returns the Google Ads media interface. This supports uploading and fetching media objects.
Return values:
adParams()
Returns the selector of all ad params in the account.
Return values:
ads()
Returns the selector of all ads in the account.
Return values:
biddingStrategies()
Returns the selector of all flexible bidding strategies in the account.
Return values:
budgetOrders()
Returns the selector of all budget orders in the account.
Return values:
budgets()
Returns the selector of all budgets in the account.
Return values:
bulkUploads()
Provides access to bulk uploads:
FileUpload,
CsvUpload.
Return values:
campaigns()
Returns the selector of all campaigns in the account.
var campaignSelector = AdsApp.campaigns();
Return values:
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:
excludedPlacementLists()
Returns a selector of all excluded placement lists in this account.
Return values:
experiments()
Returns the selector of all experiments in the account.
Return values:
extensions()
Provides access to ad extensions that have been added to this account:
Callout,
Message,
MobileApp,
PhoneNumber,
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:
keywords()
Returns the selector of all keywords in the account.
Return values:
labels()
Returns the selector of all labels in the account.
Return values:
negativeKeywordLists()
Returns a selector of all negative keyword lists in this account.
Return values:
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:
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:
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:
productAds()
Returns the selector of all product ads in the account.
Return values:
productGroups()
Returns the selector of all product groups in the account.
Return values:
report(query, optArgs)
Fetches a Google Ads report.
Example usages:
var report1 = AdsApp.report(
'SELECT Query, Ctr ' +
'FROM SEARCH_QUERY_PERFORMANCE_REPORT ' +
'DURING 20130101,20130301');
var report2 = AdsApp.report(
'SELECT AdGroupId, Id, KeywordText, Impressions, Clicks ' +
'FROM KEYWORDS_PERFORMANCE_REPORT ' +
'DURING 20130101,20130301', {
includeZeroImpressions: false,
returnMoneyInMicros: true,
apiVersion: 'v201809'
});
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: '14'
});
Reports are specified via an AWQL or GAQL query. For AWQL details, please see the AWQL guide and the list of report types and fields. For GAQL
details, please 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 AWQL queries, the AdWords API version to query. Sunsetted versions are not allowed.
For GAQL queries, the Google Ads API version to query. Sunsetted versions for GAQL queries are
also 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:
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: '14'
});
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 AdWords 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:
Provides access to shopping ad group-level targeting criteria, currently just audiences.
Return values:
Returns the selector of all shopping ad groups in the account.
Return values:
Provides access to shopping campaign-level targeting criteria, currently just audiences.
Return values:
Returns the selector of all shopping campaigns in the account.
Return values:
targeting()
Provides access to campaign-level targeting criteria: device targeting, ad scheduling, location
targeting, and audiences.
Return values:
userlists()
Returns the selector of all user lists in the account.
Return values:
videoAdGroups()
Returns the selector of all video ad groups in the account.
Return values:
videoAds()
Returns the selector of all video ads in the account.
Return values:
videoCampaigns()
Returns the selector of all video campaigns in the account.
Return values:
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:
