My favorites ▼ | English ▼ | Sign in

Google Custom Search APIs and Tools

Defining Your Search Engine Specifications

The Basics page introduced you to the components of custom search engines. This page shows you how you can define your search engine specifications using a context file.

Contents

This page includes the following sections:

Overview

A context file describes the structure of your search engine and defines its behavior. The best way to start learning about context files is by viewing a simple example. As you build your confidence, you might want to start experimenting with various elements and attributes. You can play with the settings in the control panel, and then view the generated XML version in the Advanced tab.

The following code describes a search engine for climate change. Note that this search engine has image search enabled.

<CustomSearchEngine volunteers="false"
                    keywords="climate &quot;global warming&quot; &quot;greenhouse gases&quot;"
                    language="en"
                    visible="false"
                    encoding="UTF-8">
    <Title>RealClimate</Title>
    <Description>Science behind global warming and climate change.</Description>
    <Context>
      <BackgroundLabels>
        <Label name="_cse_hwbuiarvsbo" mode="FILTER"/>
        <Label name="_cse_exclude_hwbuiarvsbo" mode="ELIMINATE"/>
      </BackgroundLabels>
    </Context>
    <LookAndFeel nonprofit="false"/>
    <ImageSearchSettings enable="true" layout="1" />
</CustomSearchEngine>

CustomSearchEngine elements

A basic context file includes the following main elements and child elements.

Element Required Description
CustomSearchEngine Required Encloses all information about the search engine. Has the following attributes:
  • keywords. Specifies a list (up to 100 characters long) of space-separated keywords associated with the search engine. If not specified, Custom Search will use an empty value.
  • language. Specifies one of the supported languages to display in the user interface. Specifying a language will boost results in that language, but will not filter out results in other languages. If not specified, Custom Search will use en (English). If the value is null, Custom Search will use the language of the locale of your user.
  • visible. Indicates whether your search engine, once it becomes popular, should be included in the Custom Search directory or not. Allowed values are true (default) or false. Note that even if your search engine is not listed, people can still find it if they know the URL of its home page.
  • encoding. Specifies the encoding for your search results page. If you're embedding a search box on your home page, this value must match the encoding of your home page. Default value (recommended) is UTF-8. Encoding values.
  • autocompletions. Indicates whether Custom Search should generate GLOSSARY autocompletions for your search engine. Allowed values are true or false. If true, note that generating autocompletions can take several hours. After setting this value, you must modify your search box code to request autocompletions. You can get the updated code from the Get code tab in the control panel or by programmatically retrieving the search box code. Only search engines that search included sites—a predetermined collection of websites—can have autocompleted queries.
Title Required The name of your search engine. It appears on your custom search engine homepage and the result pages.
Description Required The descriptive text that appears in your search engine homepage.
Context Required Holds information about labels. Includes the child elements BackgroundLabels and Facet.
BackgroundLabels Optional Container for labels used to promote, include, or excludes sites and pages. Includes one or more child Label elements.
Label Optional Label used to promote sites or determine inclusion/exclusion of sites. Has the following attributes:
  • name. The label name.
  • mode. FILTER (promotes or exclusively shows preferred sites) or ELIMINATE (excludes site). You can customize these labels as you wish.
LookAndFeel Required Determines whether your search results show ads and controls the look and feel of your search engine. It has multiple attributes and child elements that are described in detail in the Designing the Look and Feel page.

Only legitimate non-profit organizations may use a free Google Custom Search engine without ads. If your custom search engine is not for a registered non-profit organization, but you do not want Google to display ads in the search results page, consider upgrading to Google Site Search.

The element has one attribute, nonprofit, and takes one of the following values:

  • false (default). Google displays ads with your search results page. You can share in the ad revenue.
  • true. If you're creating a search engine on behalf of a registered non-profit organization, Google will not display ads in the search results page.
AdSense Optional Associates the search engine with your AdSense account. Make money with your custom search engine by connecting it with your Google AdSense account. When users click on an ad in your search results, you get a share of the ad revenue. If you already have an existing AdSense account, do not create a new one, even if you create multiple search engines. Google automatically associates your search engines with the same AdSense account. Creating another AdSense account might result in the termination of your AdSense account.
EnterpriseAccount Optional If you upgraded to Google Site Search, it lists your contact information. You can change the attribute values to update your information.
ImageSearchSettings Optional

Specifies if Image Search is enabled. Has the following attributes:

  • enable. Specifies whether Image Search is enabled for this search engine. Allowed values are true or false.
  • layout. Specifies the layout of the image search results tab. Allowed values are:
    Value Layout
    0 Google Custom Search Image layout option - Classic
    1 Google Custom Search Image layout option - Column
    2 (default) Google Custom Search Image layout option - Popup

Taking the Next Step

After you create the context file that defines the specification of your search engine, you can start listing the sites for your custom search engine.

 

< Back to The Basics of Custom Search | Forward to Selecting Sites to Search >