Home Guides Reference Code Generator

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
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

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.

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 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. Refer to the ie parameter for the full list of possible values.
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.

By default personalizedAds is set to true.

Example: 

'personalizedAds': false
styleId Optional
The custom search style ID of the ad, indicating which predefined style to use. Learn more about using custom search styles. Note that with the styleId set for a request, ads will be rendered with the style, and other styling parameters for ad elements such as font color, font size, etc. will be ignored.

Example: 

'styleId': '1234567891'

Layout & Styling

Parameter Description and Examples
colorLocation Optional
Specifies the color of the location extension. The default color is #666666.

Example:

'colorLocation' : '#000000'
domainLinkAboveDescription Optional

Specifies that the visible URL line will be displayed above the description line for each ad. This only applies to the 3 line ad format.

Displaying the visible URL above the description is the default behavior. If you wish to see the URL below the description use this line of code:

'domainLinkAboveDescription': false
fontSizeLocation Optional
Specifies the font size of the location extension. The default font size is 12px.

Example:

'fontSizeLocation' : 14

Ad Extensions

Parameter Description and Examples
clickToCall (mobile only) Optional

Note: This ad extension is for mobile implementations only. Call extensions are ad extensions that allow advertisers to include their phone number in their ads. These extensions add a clickable phone number to the ad, making it easy for customers to calladvertisers directly.
When a user clicks the phone number, the browser launches the system dialer and initiates a call.


By default, call extensions are not enabled. If you wish to enable them use this line of code:

'clickToCall' : true
location Optional

Provides a way for the ad to display location information such as the address. See example below:


By default, location extensions are enabled . If you wish to disable them use this line of code:

'location' :  false
sellerRatings Optional

Seller rating extensions provide user-submitted ratings information about sellers next to their ads. These reviews reflect users' buying experience with these businesses, rather than their experience with particular products.

This feature is offered as a service to our users to let them know about advertisers who are rated well by their customers while viewing relevant ads. This helps users make more informed web browsing and purchase decisions while helping advertisers increase their potential for earning more qualified leads. See example below:


By default, seller rating extensions are enabled . If you wish to disable them use this line of code:

'sellerRatings' :  false
siteLinks Optional

Ad Sitelinks is a feature that lets advertisers include additional links to deeper content on their site beyond the main landing page. Sitelinks extend the value of ads by showcasing additional targeted and relevant links for users whose search queries have triggered these ads. See example below:


By default, site link extensions are enabled . If you wish to disable them use this line of code:

'siteLinks' :  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 id='afscontainer1'></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 unit in pixels.

Example: 

'width' : '700px'

Configuration Settings

Parameter Description and Examples
number Optional
The number of ads which should appear in this unit. The default value is 2.

Example: 

'number' : 4

Font

Parameter Description and Examples
fontFamily Optional
Specifies the font family of the entire ad unit. On desktop, the default font is Arial; on mobile, the default fonts are Roboto (Android) and Helvetica Neue (iOS) This parameter supports a comma-separated list of fonts. CSA will use the first font from the list that is supported by the user's browser.

Supported font families are:
  • 'verdana'
  • 'arial'
  • 'tahoma'
  • 'times new roman'
  • 'georgia'
  • 'trebuchet ms'
  • 'roboto'
  • 'helvetica neue'
  • 'meiryo'
  • 'ms gothic'

Examples: 

'fontFamily' : 'georgia'
'fontFamily' : 'verdana, arial, times new roman'
fontFamilyAttribution Optional
Specifies the font family of the entire ad unit. On desktop, the default font is Arial; on mobile, the default fonts are Roboto (Android) and Helvetica Neue (iOS) This parameter supports a comma-separated list of fonts. CSA will use the first font from the list that is supported by the user's browser.

Supported font families are:
  • 'verdana'
  • 'arial'
  • 'tahoma'
  • 'times new roman'
  • 'georgia'
  • 'trebuchet ms'
  • 'roboto'
  • 'helvetica neue'
  • 'meiryo'
  • 'ms gothic'

Examples: 

'fontFamilyAttribution' : 'georgia'
'fontFamilyAttribution' : 'verdana, arial, times new roman'
fontSizeAnnotation Optional
Specifies the size (in pixels) of the text annotations (e.g. siteLinks). Valid values are from 8-16px. Note that the maximum difference allowed between font sizes within an ad unit (i.e. title, description, attribution, visible URL, ad extensions) is 6px.

Example: 

'fontSizeAnnotation' : 14
fontSizeAttribution Optional
Specifies the size (in pixels) of the attribution. Valid values are from 8-16px. The default size is 13px. Note that the maximum difference allowed between font sizes within an ad unit (i.e. title, description, attribution, visible URL, ad extensions) is 6px.

Example: 

'fontSizeAttribution' : 14
fontSizeDescription Optional
Specifies the size (in pixels) of the ad description text. Valid values are from 8-16px. Default size is 12px. Note that the maximum difference allowed between font sizes within an ad unit (i.e. title, description, attribution, visible URL, ad extensions) is 6px.

Example: 

'fontSizeDescription' : 10
fontSizeDomainLink Optional
Specifies the size (in pixels) of the link to the advertiser's site. Valid values are from 8-16px. Default size is 12px. Note that the maximum difference allowed between font sizes within an ad unit (i.e. title, description, attribution, visible URL, ad extensions) is 6px.

Example: 

'fontSizeDomainLink' : 14
fontSizeTitle Optional
Specifies the size (in pixels) of the ad title. Valid values are from 8-16px. Default size is 12px. Note that the maximum difference allowed between font sizes within an ad unit (i.e. title, description, attribution, visible URL, ad extensions) is 6px.

Example: 

'fontSizeTitle' : 12

Color

Parameter Description and Examples
colorAdBorder Optional
Places a border in the specified color around an individual ad and creates a "box" look around each ad.

Example: 

'colorAdBorder' : '#ADDFFF'
colorAdSeparator Optional
Places a 1px border between the ads in an ad block. The default is off with no border between ads.

Example: 

'colorAdSeparator' : '#000000'
colorAnnotation Optional
Specifies the color of the text annotations (e.g. siteLinks). By default, text annotations are #666666.

Example: 

'colorAnnotation' : '#666666'
colorAttribution Optional
Specifies the color of the attribution. The default color of the attribution is #666666.

Example: 

'colorAttribution' : '#996699'
colorBackground Optional
Specifies the background color of the ad.

Example: 

'colorBackground' : '#FFFFFF'
colorBorder Optional
Specifies a 1px border color for the ad unit. If none is provided the ad unit will have no border.

Example: 

'colorBorder' : '#0099FF'
colorDomainLink Optional
Specifies the color of the link to the advertiser's site.

Example: 

'colorDomainLink' : '#000000'
colorText Optional
Specifies the color of the ad description text.

Example: 

'colorText' : '#000000'
colorTitleLink Optional
Specifies the color of the ad title.

Example: 

'colorTitleLink' : '#000000'

General Formatting

Parameter Description and Examples
adBorderSelections Optional
Specifies border lines for each ad in the ad unit. This must be used in conjunction with the colorAdBorder parameter. The following values are valid for adBorderSelections:
  • 'top'
  • 'right'
  • 'bottom'
  • 'left'

Example: 

'adBorderSelections': 'top, right'

This would place a border at the top and right sides of the ad unit.
adjustableLineHeight Optional
Specifies the line height for the title, description, and visible url ad elements. Note that the line height includes the ad element text. If the line height is greater than the text,the text is centered vertically and the remaining pixels are distributed equally as padding above and below the text.

Example: 

'lineHeightTitle' : 14
'lineHeightDescription' : 16
'lineHeightDomainLink' : 18
adslabel Deprecated

Use detailedAttribution to display the user query in the attribution.
attributionSpacingBelow Optional

Specifies the amount of vertical spacing between the attribution and the ads in pixels. Note that 4px of padding are automatically added and this value specifies the number of additional pixels. The default value of attributionSpacingBelow is 0. The min value is 0 and the max value is 40.

Example: 

'attributionSpacingBelow' : 2
borderSelections Optional
Specifies border lines for the ad unit. This must be used in conjunction with the colorBorder parameter. The following values are valid for borderSelections:
  • 'top'
  • 'right'
  • 'bottom'
  • 'left'

Example: 

'borderSelections': 'top, right'
This would place a border at the top and right sides of every ad in the ad unit.
noTitleUnderline Optional
Specifies whether or not the ad title will be underlined.

Example: 

'noTitleUnderline': true
titleBold Optional
Allows the entire ad title line to be bold. By default, titleBold is set to false.

Example: 

'titleBold' : true
verticalSpacing Optional
Specifies the amount of vertical spacing between ads in pixels. Note that 4px of padding are automatically added to the top and bottom of each ad for a total of 8 pixels. The default value for verticalSpacing is 4, the min is 2, and the max is 12. So the minimum padding between ads is 4px(top) + 4px(bottom) + 2px (minimum vertical space) = 10px. Total vertical spacing between ads= 4px(top) + 4px(bottom) + verticalSpacing.

Example: 

'verticalSpacing' : 5

Ad Extensions

Parameter Description and Examples
detailedAttribution Optional

Extends the attribution to include the user query. See example below:


By default, detailed attribution is enabled . If you wish to disable this use the following line of code:

'detailedAttribution' :  false