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 ^Updated!
• The Attributes of the CustomSearchEngine Element
• The Child Elements of CustomSearchEngine ^Updated!
• The Context Element
• Taking the Next Step

Overview ^Updated!

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.

<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"/> 
</CustomSearchEngine>

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

• CustomSearchEngine
  • Title
  • Description
  • Context
    • BackgroundLabels
      • Label
  • LookAndFeel

CustomSearchEngine is the main element that describes the search engine. It encloses the metadata that describes your search engine, and it has attributes and child elements. Except for Label (and an optional element, none of its child element can have a sibling; that is, you can have only one Title element, one Description element, and one Look and Feel element.

The context file also have other optional elements that you would only need to define if you want to enable other features. They have the following structure:

• CustomSearchEngine
  • SubscribedLinks
  • AdSense
  • EnterpriseAccount

When you are ready to create your context file, do not create it from scratch. Download and modify the context file generated by the control panel. For instructions, see The Basics page.

Back to top

The Attributes of the CustomSearchEngine Element

All the CustomSearchEngine attributes are optional, which means that you do not have to use them, and Custom Search will just use the default value. For example, if you do not define the language and encoding attributes of the CustomSEarchEngine element, Custom Search will interpret that to mean that the language value is "en" (English) and the encoding value is "UTF-8".

The following is an example of a CustomSearchEngine element with fully defined attributes:

<CustomSearchEngine volunteers="false"
                    keywords="climate &quot;global warming&quot; &quot;greenhouse gases&quot;"
                    language="en"
                    visible="false"
                    encoding="UTF-8">
</CustomSearchEngine>      

The following table lists the optional attributes of CustomSearchEngine and their values.

Back to top

The Child Elements of CustomSearchEngine ^Updated!

The following tables list the required and optional child elements of CustomSearchEngine; these elements should all be nested within the <CustomSearchEngine> </CustomSearchEngine> tags. The content of your definition should be within the opening and closing tags of the child element. For example:

<CustomSearchEngine>
    <!--The following are the required elements-->
    <Title>Sample Search Engine</Title>
    <Description>Search engine to illustrate the elements in a Custom Search context file</Description>
    <Context> ... </Context>
    <LookAndFeel nonprofit="false">... </LookAndFeel>
    <!--The following are elements for enabling other features-->
    <SubscribedLinks />
    <Adsense />
    <EnterpriseAccount />
    <t13n_languages>hi</t13n_languages>    
</CustomSearchEngine>            

Required Elements ^Updated!

This table lists child elements that you must include in your context files.

<LookAndFeel nonprofit="false"/>

Back to top

Optional Elements ^New!

The table list child elements that you do not need to include in your context file unless you want to activate the features, which are discussed in greater detail in other pages in the developer's guide.

Back to top

The Context Element

The Context element, which is one of the child elements of CustomSearchEngine, houses information about labels. It has two child elements: BackgroundLabel and Facet. Facet elements have to do with refinement labels, which let you help your users refine their search. This section will mostly discuss the BackgroundLabel element. If you decide to add refinements to your search results, you can learn more about the Facet element, which is described in greater detail in the Helping Your Users Refine their Searches page.

The Context section of a simple context file (one that does not include refinement labels) might look like the following:

    <Context>
      <BackgroundLabels>
        <Label name="_cse_hwbuiarvsbo" mode="FILTER"/>
        <Label name="_cse_exclude_hwbuiarvsbo" mode="ELIMINATE"/>
      </BackgroundLabels>
    </Context>

It has the following structure:

• Context
  • BackgroundLabels (labels for the search engine)
    • Label (for promoting sites or for showing certain sites exclusively)
    • Label (for excluding sites)

Custom Search associates the context specifications with the annotations through search engine labels. The context section includes labels that identify the search engine; you then use these search engine labels to tag each site in the annotations file.

The context section starts out with two search engine labels under BackgroundLabels. One search engine label either promotes or exclusively shows only the preferred sites, and the other label excludes sites. Custom Search displays search results based on how sites have been annotated with these two labels. To learn more about search engine labels, see Changing the Ranking of Your Search Results.

Custom Search generates two search engine labels for each of your search engines, but you can change these labels to something that is more meaningful to you. When you start creating more labels, you might want to name them according to how they affect the search results. For example, if a label is meant to exclude sites about vegetables you despise, then its name could be cse_exclude_boringvegetables. The label names should be unique across your search engines. If you change the name of the search engine label in the context file, you have to update all the annotations that have been tagged with the old search engine label.

Back to top

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 >