Reference

Parameters

Page Level Parameter Descriptions

These parameters only need to be specified once per page. They affect all units on the page.

Required

Parameter Description and Examples
adPage Required when the user navigates to the next results page or previous results page.

The adPage parameter specifies the results page ads are being displayed on. This parameter is used when users navigate past the first page of search results. For example, if five ads are requested, and the adPage parameter is set to 2, the returned ads will be the second page of five ads.

pubId Required
This is your AdSense client-ID. Your pubId is the part of your client-ID that comes after 'partner-'. For example, if your client-ID is 'partner-test-property', your pubId is 'test-property'. This is standard protocol for CSA.

Example: 

'pubId' : 'test-property'
query Required, except on Related Search on Content pages.
This is the search query entered by the user. The value of the query parameter should be unencoded.

Note: Using this parameter on Related Search on Content pages will cause unexpected results.

Examples: 

'query' : 'flowers'
 
'query' : 'black & decker'
 
'query' : myQuery // myQuery is a variable containing the search query
resultsPageBaseUrl Required when there are related search units on the page.
Specifies the URL of the search results page on which the search query is the related search term the user has clicked on. The resultsPageBaseUrl may include its own parameters, except the search query which will be appended automatically.

Example: 

'resultsPageBaseUrl' : 'http://www.example.com/search?a=v1&b=v2'
relatedSearchTargeting Required when there are related search units on the page.
This parameter is mandatory when related search units are requested. It controls what type of Related Search experience is displayed, depending on the page context:
  • 'content' Use this option for Related Search on Content pages (e.g., articles, blog posts).
  • 'query' Use this option exclusively for Related Search on Search results pages.

Note:The relatedSearchTargeting page parameter is automatically set to 'query' by default. However, it's crucial to note that this default value is specifically designed for search results pages only (Related Search on Search). If you are using related search on any other type of page (e.g., articles, blog posts), you must explicitly set the parameter to 'content'.

Note: The following guidelines apply to use of this parameter:

  • Certain related search features may be enabled or disabled depending on the value of this page parameter.
  • Misrepresenting the type of page or relying on the default 'query' setting for the relatedSearchTargeting parameter on non-search results pages is considered a violation of these written instructions.
  • Google may periodically verify the accuracy of this value, regardless of whether it's set manually or using the default.

Examples:

'relatedSearchTargeting' : 'content'
 
'relatedSearchTargeting' : 'query'
styleId Required
Specifies the ID of the custom search style to be applied to the ad or related search units on the page. Learn more about using custom search styles. Note that with the styleId set for a request, ads or related searches will be rendered with the style, and legacy styling parameters will be ignored. If styleId is not specified in the request, a system default style will be rendered.

Example: 

'styleId': '1234567890'

Optional

Parameter Description and Examples
linkTarget Optional
Specifies whether clicking on an ad opens up in the same window or a new window. The default is '_top'. This parameter can also be used at the unit level.
  • '_top' Opens in the same window.
  • '_blank' Opens in a new window.

Example: 

'linkTarget' : '_blank'
referrerAdCreative Optional
If a user arrives at your content page which contains a Related Search for Content unit by clicking an ad or link on another website, and that ad or link is under your control, this parameter should be set to the creative text of that ad or link verbatim.

The following guidelines apply to use of this parameter:

  • The parameter should only be provided on a Related Search for Content request, and it will be ignored on all other requests.
  • It should only be used on the traffic that you intentionally source from other websites, and should not be used on organic traffic.
  • It should include the title line, the description, and/or any other wording in the ad or link creative.
  • Omitting values from the ad or link creative (or including additional values) is considered a violation of these written instructions.
  • It is case insensitive.
  • It accepts valid UTF-8 encoding; unicode characters / diacritics are supported.
  • Google may use or ignore the parameter you submit. When used, it may affect the selection and ranking of the terms.

Note: This parameter is required when using the terms parameter.

Examples: 

'referrerAdCreative': 'search for ads related to dental implants'

'referrerAdCreative': 'The Early Signs of Psoriatic Arthritis'
resultsPageQueryParam Optional
Specifies the name of the URL parameter for the search query on the search results page. Defaults to ‘q’ if not specified.

Example: 

'resultsPageQueryParam' : 'query'
terms Optional
This parameter allows you to supply a comma-delimited list of your own related search terms to be returned with a related search request, though Google may or may not use the terms provided here.

Note: When using this parameter, referrerAdCreative is also required and relatedSearchTargeting is required and must be set to 'content'.

Examples: 

'terms' : 'cars rental, flight ticket'
ignoredPageParams Optional
Specifies the list of URL parameters for a content page with a Related Search for Content unit that can be safely ignored without impacting the core content or user experience.

Note: Before related search terms can appear on your site, Google needs to crawl your pages to ensure the terms are contextually relevant. When a page has not yet been crawled or is blocked from crawling (eg. by a robots.txt) by the AdSense crawler, we will not show suggested Related Search terms you provide to Google.

The Related Search on Content product relies on Google's content crawling system to index pages and generate relevant search terms. Content page URLs containing query parameters such as tracking variables, user IDs, session IDs, or other dynamic identifiers can interfere with the crawler's ability to assess the page's core content and may lead to inaccurate or irrelevant related search terms. This page parameter instructs Google's crawler to disregard these nonessential parameters, ensuring proper content indexing and reducing unnecessary crawl load. This allows Google to better recognize a page as having already been crawled and start showing suggested terms (both Google and the partner's, if eligible).

The following guidelines apply to use of this parameter:

  • The parameter should only be provided on a Related Search for Content request, and it will be ignored on all other requests.
  • The value of this parameter should be a comma-delimited list of URL parameters that may appear when any user navigates to the content page.
  • It is case sensitive.
  • When any URL parameter from this list is removed from the content page's URL, there should be no significant impact the pages content, appearance, or user experience.
  • Including a URL parameter that does significantly impact the pages content, appearance, or user experience is considered a violation of these written instructions.
  • Google may periodically verify the effect of ignoring the provided URL parameters.

Examples:
A user visits a content page and where the URL is: 

http://example.com/content?utm_medium=social&page_id=123&click_id=456
 Providing the following ignorable URL parameters: 
'ignoredPageParams' : 'utm_medium,click_id,session_ref'
 Would treat the content page's URL as: 
http://example.com/content?page_id=123

Configuration Settings

Parameter Description and Examples
adsafe Optional
Specifies the filtering rules that Google should apply to ads matching the search query. The following are the valid settings for adsafe and the effect each value has on returned ads:
  • 'high' Returns family-safe ads. Does not return non-family-safe or adult sexual content ads.
  • 'medium' Returns family-safe and non-family-safe ads. Does not return adult sexual content ads.
  • 'low' Returns all types of ads.

By default adsafe is set to high.

Example: 

'adsafe': 'medium'
adtest Optional
The adtest parameter is used to indicate that a request for ads is a test. When the adtest parameter has a value of on, Google treats the request as a test and does not count the ad impressions or track the clickthrough results.

When the adtest parameter has a value of on, you do not generate any revenue.

Ad requests with the adtest parameter set to on coming from a domain that hasn't been approved in the Sites tab will return ads that have a "test ad" overlay and are unclickable.

Use this parameter when testing, but do not use it in production systems or you will not be paid for ads that you display.

The default adtest value is off.

Example: 

'adtest' : 'on'
channel Optional
You may include an AdSense for Search channel for tracking the performance of different pages. Use the unique channel ID created in your AdSense account or by your Technical Account Manager. Learn more about channels here.

Multiple channels should be separated by the '+' symbol.

Examples: 

'channel' :  'testA'  
'channel' :  'testA+testB'
hl Optional
This parameter identifies the language that the requested ads or related searches should target. The default value is en.

Google supports all AdWords API language codes.

Note: Advertisers specify the languages that their ads target. If you include this parameter in your request, Google only returns ads that are targeted for that language or targeted for all languages but it does not guarantee that the ad text will be in the specified language.

Typically, you should set the hl parameter to the primary language of the page from which this parameter is sent.

Examples: 

'hl' : 'es'
ie Optional

The ie parameter sets the character encoding scheme that should be used to interpret the query string.

The default ie value is utf-8.

Value Standard name Associated Supported Languages
latin1 ISO-8859-1 Western European (Catalan, Danish, Dutch, English, Finnish, French, German, Indonesian, Italian, Norwegian, Portuguese, Spanish, Swedish)
latin2 ISO-8859-2 Eastern European (Croatian, Czech, Hungarian, Polish, Romanian, Serbian, Slovak, Slovenian)
latin3 ISO-8859-3  
latin4 ISO-8859-4 Baltic (Estonian, Latvian, Lithuanian)
cyrillic ISO-8859-5 Bulgarian, Russian
arabic ISO-8859-6  
greek ISO-8859-7 Greek
hebrew ISO-8859-8 Hebrew
latin5 ISO-8859-9  
latin6 ISO-8859-10 Icelandic
euc-jp EUC-JP Japanese
euc-kr EUC-KR Korean
sjis Shift_JIS Japanese
big5 Big5 Traditional Chinese
gb GB2312 Simplified Chinese
utf-8 UTF-8 All
oe Optional

The oe parameter sets the character encoding scheme that Google should use to encode the text of the ads. While technically optional, it's good practice to pass a value for this parameter.

The default oe value is utf-8.

Value Standard name Associated Supported Languages
latin1 ISO-8859-1 Western European (Catalan, Danish, Dutch, English, Finnish, French, German, Indonesian, Italian, Norwegian, Portuguese, Spanish, Swedish)
latin2 ISO-8859-2 Eastern European (Croatian, Czech, Hungarian, Polish, Romanian, Serbian, Slovak, Slovenian)
latin3 ISO-8859-3  
latin4 ISO-8859-4 Baltic (Estonian, Latvian, Lithuanian)
cyrillic ISO-8859-5 Bulgarian, Russian
arabic ISO-8859-6  
greek ISO-8859-7 Greek
hebrew ISO-8859-8 Hebrew
latin5 ISO-8859-9  
latin6 ISO-8859-10 Icelandic
euc-jp EUC-JP Japanese
euc-kr EUC-KR Korean
sjis Shift_JIS Japanese
gb GB2312 Simplified Chinese
utf-8 UTF-8 All
ivt Optional
This parameter allows you to supply a boolean that informs Google that you wish to allow ads that use an invalid traffic-only cookie & local storage on both consented and unconsented traffic.
  • true When this parameter isn't present or you set it to "true," we will set an invalid traffic-only cookie and use local storage on consented traffic only.
  • false When you set this parameter to "false" we will set an invalid traffic-only cookie and use local storage on both consented and unconsented traffic.

By default IVT is set to true.

Example: 

'ivt': false

Unit Level Parameter Descriptions

These parameters affect the way individual ad units on a page are presented to the user each parameter can be set individually for each ad unit.

Required

Parameter Description and Examples
container Required
The id of the empty ad container <div> where the ad should appear.

Example: 

'container' : 'afscontainer1'
maxTop Required when the ad unit is above the search results.

Use this parameter to specify the number of ads to be shown on the top ad unit.

Note: This parameter is used in place of the 'number' parameter. This ad unit should be wide enough so the first line of the ads doesn't wrap. Using the maxTop parameter on any other placement on the page is a policy violation.

Example:

'maxTop' : 4
width Required
Specifies the width of the ad or related search unit in pixels.

Example: 

'width' : '700px'
 
'width' : 700

Configuration Settings

Parameter Description and Examples
adLoadedCallback Optional
Specifies a JavaScript function to be called when the ads or related searches have loaded or when no ads or related searches are served. The parameter should be set to a JavaScript callback function that you implement which allows an action to be performed when the ad call is complete.

The callback function takes following parameters:

containerName Container name of the ad or related search unit.
adsLoaded Set to true when there is at least one ad or related search term to display and false when there are no ads or related searches returned.
isExperimentVariant Set to true if a custom styling experiment is running and the variant of the experiment is chosen to render the ads.
callbackOptions A JSON object that contains following fields:
termPositions: For a related search block, contains a map<string,int> of publisher provided terms to zero-indexed position of these terms in the response. If a term is provided but not returned, it will not appear in the map.

Note: Please test your callback function to ensure it does not generate any errors, especially those that might interfere with the loading of your page.

Example of a JavaScript callback: 

var adblock1 = {
  'container' : 'adblock1_div_id',
  'adLoadedCallback' : function(containerName, adsLoaded,
    isExperimentVariant, callbackOptions) {
    if (adsLoaded) {
       try {
         // most likely do nothing
       } catch (e) {
         alert ("Error in callback function");
         // Do something to handle error gracefully
       }
    } else {
       // as you always do when there is no ad coverage from Google
    }
  }
};
number Optional
The number of ads which should appear in this unit. The default value is 2.

Example: 

'number' : 4
relatedSearches Optional
The number of related searches that should appear in this unit. Defaults to 0 if not specified.

Example: 

'relatedSearches' : 4