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:
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,
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:
keywords()
Returns the selector of all keywords in the account.
Return values:
labels()
Returns the selector of all labels in the account.
Return values:
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:
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:
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:
newExperimentBuilder()
Returns the builder for creating an experiment.
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:
Returns the selector of all performance max campaigns in the 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:
recommendations()
Returns the selector of all recommendations in the account.
Return values:
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:
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:
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:
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:
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: