Custom Search Ads

Custom Search Ads parameter descriptions

Next: Use conditional styling to apply multiple search styles to your search results pages

For advanced users we've provided this list of the currently supported search style parameters. The code you generate in AdSense contains all of the most commonly used parameter settings. There are two required parameters: pubId and query. AdSense provides the pubId but you must edit the code and pass a value for the query parameter. All of the other parameters are optional and are described below.

Parameter types

There are two types of parameters:

Page level parameters which apply to all ad units on the page
Unit level parameters which apply to individual ad units.

Here's some example output from the code generator with two ad blocks. To configure this code, you must set the required query parameter in the pageOptions map (e.g., “query”: myQuery). This is all that’s required to start showing ads. You can also set optional page level parameters in the page level block and individual unit level parameters in the adblock1 and adblock2 maps.

<div id="afscontainer1"></div>
<div id="afscontainer2"></div>

<script type="text/javascript" charset="utf-8">

  // Page level parameters
  var pageOptions = {
    "pubId": "partner-pub-1234567891234567",
    "styleId": "1234567890",
    "query": myQuery,
  };

  // Unit level parameters
  var adblock1 = {
    "container": "afscontainer1"
  };

  var adblock2 = {
    "container": "afscontainer2"
  };

  _googCsa('ads', pageOptions, adblock1, adblock2);

</script>

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 This is the search query entered by the user. The value of the query parameter should be unencoded. Examples: `'query' : 'flowers'` `'query' : 'black & decker'` `'query' : myQuery // where myQuery is a JavaScript 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 `resultsPageBaseUr`l 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'`
`styleId`	Required Specifies the ID of the search style to be applied to the ad or related search units on the page. Learn more about using 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'`
`maxTermLength`	Optional Specifies the maximum number of characters of a related search term including spaces. No maximum if not set. Example: `'maxTermLength' : 50`
`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 may never be used on organic traffic. It may include the title line and/or description of the ad or link creative. 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. 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. Example: `'terms' : 'cars rental, flight ticket'`

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.

Note: 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.

Note: 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 you created in your AdSense account. Learn more about tracking ad performance with custom channels.

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 should target. The default value is 'en'.

Google supports all Google Ads 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

personalizedAds

Optional
Specifies whether users have consented to allowing the publisher to share personal information with Google for the purpose of personalized advertising.

true Returns query targeted ads and some ads that may be targeted with the user's Google cookies. If the user is located in the European Union, the user must first consent to allowing your site to share personal information with Google for the purpose of personalized advertising.
false Returns only query targeted ads. This will not return any ads that are targeted with the user's Google cookies. If a user has declined consent for allowing your site to share personal information with Google for the purpose of personalized advertising, you must set this value to false.

Note: By default personalizedAds is set to 'true'.

Example:

'personalizedAds': 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

Parameter	Description and examples
`container`	Required The id of the empty ad container `<div id='afscontainer1'></div>` where the ad should appear. Example: `'container' : 'afscontainer1'`
`maxTop`	Required 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 unit or related search unit in pixels. Examples: `'width' : '700px'` `'width' : 700`

container

Required
The id of the empty ad container <div id='afscontainer1'></div> where the ad should appear.

Example:

'container' : 'afscontainer1'

maxTop

Required

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 unit or related search unit in pixels.

Examples:

'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

Was this helpful?

How can we improve it?