AdsApp.​Keyword

AI-generated Key Takeaways

• Represents a keyword within Google Ads, offering various methods for management and analysis.

• Enables control over keyword settings like bidding, labels, and URLs, along with activation and pausing.

• Provides access to performance data through stat retrieval for specific date ranges.

• Allows retrieval of keyword attributes such as ID, match type, quality score, and approval status.

• Facilitates ad param creation and management, enabling dynamic insertion of values into ad text.

Represents a Google Ads keyword.

Methods:

Member	Type	Description
adParams()	AdsApp.AdParamSelector	Creates a selector of all ad params belonging to this keyword.
applyLabel(name)	void	Applies a label to the keyword.
bidding()	AdsApp.KeywordBidding	Provides access to this keyword's bidding fields.
clearDestinationUrl()	void	Clears the destination URL of the keyword.
enable()	void	Enables the keyword.
getAdGroup()	AdsApp.AdGroup	Returns the ad group to which this keyword belongs.
getApprovalStatus()	String	Returns the approval status of the keyword.
getBaseAdGroup()	AdsApp.AdGroup	Returns the base ad group to which this keyword belongs.
getBaseCampaign()	AdsApp.Campaign	Returns the base campaign to which this keyword belongs.
getCampaign()	AdsApp.Campaign	Returns the campaign to which this keyword belongs or null if it does not belong to a search or display campaign.
getEntityType()	String	Returns the type of this entity as a String, in this case, "Keyword".
getFirstPageCpc()	double	Returns the first page cpc for the keyword.
getId()	String	Returns the ID of the keyword.
getMatchType()	String	Returns the match type of the keyword.
getQualityScore()	int	Returns the quality score of the keyword, in 1..10 range.
getResourceName()	String	Returns the resource name of the keyword.
getStatsFor(dateRange)	AdsApp.Stats	Returns stats for the specified date range.
getStatsFor(dateFrom, dateTo)	AdsApp.Stats	Returns stats for the specified custom date range.
getText()	String	Returns the text of the keyword.
getTopOfPageCpc()	double	Returns the top of page cpc for the keyword.
isEnabled()	boolean	Returns true if the keyword is enabled.
isPaused()	boolean	Returns true if the keyword is paused.
labels()	AdsApp.LabelSelector	Creates a selector of all labels applied to the keyword.
pause()	void	Pauses the keyword.
remove()	void	Removes the keyword.
removeLabel(name)	void	Removes a label from the keyword.
setAdParam(index, insertionText)	void	Creates an ad param for this keyword with the specified index and insertion text.
setAdParam(index, insertionText)	void	Creates an ad param for this keyword with the specified index and insertion text.
urls()	AdsApp.KeywordUrls	Provides access to this keyword's URL fields.

adParams()

Creates a selector of all ad params belonging to this keyword.

Return values:

Type	Description
AdsApp.AdParamSelector	Selector of all ad params belonging to this keyword.

applyLabel(name)

Applies a label to the keyword. name of the label is case-sensitive. Operation will fail if the label with the specified name does not already exist in the account.

Note that the keyword cannot have more than 50 labels.

Returns nothing.

Arguments:

Name	Type	Description
name	String	Name of the label to apply.

bidding()

Provides access to this keyword's bidding fields.

Return values:

Type	Description
AdsApp.KeywordBidding	Access to this keyword's bidding fields.

clearDestinationUrl()

Clears the destination URL of the keyword. To upgrade keywords to final URL, first clear the destination URL, then set the final URL with KeywordUrls.setFinalUrl.

Returns nothing.

enable()

Enables the keyword.

Returns nothing.

getAdGroup()

Returns the ad group to which this keyword belongs.

Return values:

Type	Description
AdsApp.AdGroup	The ad group to which this keyword belongs.

getApprovalStatus()

Returns the approval status of the keyword. Possible values: APPROVED, PENDING_REVIEW, UNDER_REVIEW, DISAPPROVED.

Return values:

Type	Description
String	The approval status of the keyword.

getBaseAdGroup()

Returns the base ad group to which this keyword belongs.

Return values:

Type	Description
AdsApp.AdGroup	The base ad group to which this keyword belongs.

getBaseCampaign()

Returns the base campaign to which this keyword belongs.

Return values:

Type	Description
AdsApp.Campaign	The base campaign to which this keyword belongs.

getCampaign()

Returns the campaign to which this keyword belongs or null if it does not belong to a search or display campaign.

Return values:

Type	Description
AdsApp.Campaign	The campaign to which this keyword belongs or null if it does not belong to a search or display campaign.

getEntityType()

Returns the type of this entity as a String, in this case, "Keyword".

Return values:

Type	Description
String	Type of this entity: "Keyword".

getFirstPageCpc()

Returns the first page cpc for the keyword.

Return values:

Type	Description
double	The first page cpc for the keyword.

getId()

Returns the ID of the keyword.

Keyword IDs may be shared across ad groups. In order to uniquely identify one keyword, one must specify both its ad group ID and the keyword ID.

Return values:

Type	Description
String	The ID of the keyword.

getMatchType()

Returns the match type of the keyword. Possible values: BROAD, PHRASE, EXACT.

Return values:

Type	Description
String	The match type of the keyword.

getQualityScore()

Returns the quality score of the keyword, in 1..10 range.

Note: Starting the week of September 12, 2016, this method will return a NULL instead of a number for keywords that don't have enough impressions or metrics.clicks to determine a quality score.

Return values:

Type	Description
int	The quality score of the keyword.

getResourceName()

Returns the resource name of the keyword. A keyword can be identified by an ad_group_criterion resource name or a keyword_view resource name. This method will return an ad_group_criterion resource name although either is compatible with KeywordSelector.withResourceNames.

Return values:

Type	Description
String	The resource name of the keyword.

getStatsFor(dateRange)

Returns stats for the specified date range. Supported values:

TODAY, YESTERDAY, LAST_7_DAYS, THIS_WEEK_SUN_TODAY, LAST_WEEK, LAST_14_DAYS, LAST_30_DAYS, LAST_BUSINESS_WEEK, LAST_WEEK_SUN_SAT, THIS_MONTH, LAST_MONTH, ALL_TIME.

Example:

var stats = keyword.getStatsFor("THIS_MONTH");

Arguments:

Name	Type	Description
dateRange	String	Date range for which the stats are requested.

Return values:

Type	Description
AdsApp.Stats	The stats for the specified date range.

getStatsFor(dateFrom, dateTo)

Returns stats for the specified custom date range. Both parameters can be either an object containing year, month, and day fields, or an 8-digit string in YYYYMMDD form. For instance, March 24th, 2013 is represented as either {year: 2013, month: 3, day: 24} or "20130324". The date range is inclusive on both ends, so forDateRange("20130324", "20130324") defines a range of a single day.

Arguments:

Name	Type	Description
dateFrom	Object	Start date of the date range. Must be either a string in YYYYMMDD form, or an object with year, month and day properties.
dateTo	Object	End date of the date range. Must be either a string in YYYYMMDD form, or an object with year, month and day properties.

Return values:

Type	Description
AdsApp.Stats	The stats for the specified date range.

getText()

Returns the text of the keyword. The returned value will be formatted as follows, depending on the match type:

• shoes - broad match
• "shoes" - phrase match
• [leather shoes] - exact match

Return values:

Type	Description
String	The text of the keyword.

getTopOfPageCpc()

Returns the top of page cpc for the keyword.

Return values:

Type	Description
double	The top of page cpc for the keyword.

isEnabled()

Returns true if the keyword is enabled.

Return values:

Type	Description
boolean	true if the keyword is enabled.

isPaused()

Returns true if the keyword is paused.

Return values:

Type	Description
boolean	true if the keyword is paused.

labels()

Creates a selector of all labels applied to the keyword.

Return values:

Type	Description
AdsApp.LabelSelector	Selector of all labels applied to the keyword.

pause()

Pauses the keyword.

Returns nothing.

remove()

Removes the keyword.

Returns nothing.

removeLabel(name)

Removes a label from the keyword. name of the label is case-sensitive. Operation will fail if the label with the specified name does not already exist in the account.

Returns nothing.

Arguments:

Name	Type	Description
name	String	Name of the label.

setAdParam(index, insertionText)

Creates an ad param for this keyword with the specified index and insertion text.

Returns nothing.

Arguments:

Name	Type	Description
index	int	Defines which parameterized snippet of ad text to replace. For example, a value of 1 indicates a replacement for the {param1:default-value} token. This field equals either 1 and 2.
insertionText	int	Numeric value to insert into the ad text.

setAdParam(index, insertionText)

Creates an ad param for this keyword with the specified index and insertion text.

Returns nothing.

Arguments:

Name	Type	Description
index	int	Defines which parameterized snippet of ad text to replace. For example, a value of 1 indicates a replacement for the {param1:default-value} token. This field equals either 1 and 2.
insertionText	String	Value to insert into the ad text.

urls()

Provides access to this keyword's URL fields. See Using Upgraded URLs for more information.

Return values:

Type	Description
AdsApp.KeywordUrls	Access to this keyword's URL fields.