My favorites | English | Sign in

Google Custom Search API

Helping Your Users Refine Their Searches

The Changing the Ranking of Your Search Results page showed you how you can tweak the results using keywords and labels. This page will show you how you can help your users refine their search queries using a different kind of label, called a refinement label. Unlike search engine labels, refinement labels are visible to your users. In fact, they appear at the top of the search results page.

Contents

This page includes the following sections:

Overview

Even after you've assembled the result set for your search engine and tweaked the rankings, your users might still type queries that are too broad. For example, if users search for a health condition, it is not clear what kind of information they are looking for. Are they looking for information about symptoms, treatments, or risk factors? However, if they can select refinements, or categories of search results, they can narrow their searches and get to the answers quickly.

If you are familiar with Google search, you might have already seen refinements. They are the links right below the line Refine results for [search term]:, as you can see in the following screenshot.

Figure 1: Refinements in Google Search lets you narrow your search.

Search for "pimple" in Google search to see examples of refinement labels

Figure 2: Clicking the Treatment link refreshes the page and shows a different set of results.

Refinements are labels that you apply to sites to categorize them. The refinement labels you create appear as links at the top of your search results pages. When a user clicks one of the refinement links, sites that you have tagged with the refinement label are—depending on how you have defined the label—either searched exclusively or promoted above other results. You can even append your users' queries with additional search terms to help them retrieve more targeted results or redirect them to a different page.

Back to top

Creating Refinement Labels

You can create refinement labels and tag sites with them in the Refinements tab of the control panel, but you can have greater control over the ranking if you are using the Custom Search XML annotations file. As with the search engine labels, you define refinement labels in the context file and apply them to sites in the annotations file.

As the following example shows, refinement labels are defined using Facet elements within the Context section. 

<CustomSearchEngine>
    <Title>Universities</Title>

    <Context>

      <Facet>
        <FacetItem title="Lectures">
           <Label name="lectures" mode="BOOST" weight="0.8">
              <Rewrite>lecture OR lectures</Rewrite>
           </Label>
        </FacetItem>
      </Facet>

      <Facet>
        <FacetItem title="Assignments">
          <Label name="assignments" mode="BOOST" weight="0.8">
            <Rewrite>homework OR assignment OR assignments</Rewrite>
          </Label>
        </FacetItem>
     </Facet>

     <Facet>
       <FacetItem title="Reference">
         <Label name="reference" mode="FILTER">
            <IgnoreBackgroundLabels>true</IgnoreBackgroundLabels>
         </Label>
       </FacetItem>
     </Facet>

     <Facet>
        <FacetItem title="Papers">
          <Label name="papers" mode="FILTER"/>
          <Redirect url="http://scholar.google.com/scholar?q=$q"/>           
        </FacetItem>
      </Facet>

      <BackgroundLabels>
        <Label name="_cse_omuauf_lfve" mode="FILTER"/>
        <Label name="_cse_exclude_omuauf_lfve" mode="ELIMINATE"/>
      </BackgroundLabels>

    </Context>

  </CustomSearchEngine>

The Facet element has the following structure:

Each Facet elements can have up to four FacetItem child elements. You can create as many refinement labels as you want and display up to 16 refinement links in the search results page. But before you start creating labels and tagging sites with them, look into using pre-built labels from Custom Search.

Back to top

Example: Refinement Labels

A basic refinement labels look like the following:

      <Facet>
        <FacetItem title="Lectures">
           <Label name="lectures" mode="BOOST" weight="0.8"/></Label>
        </FacetItem>
      </Facet>

Figure 3: The sample code produces a search results page with a label.

Search results page with a refinement link called Lectures

Back to top

Elements of Refinement Labels

The following are the child elements of Facet.

Element Attribute Description Value
FacetItem title The refinement link that is displayed at the top of the results page.

 

 The title of the link. In the example above, that would be "Lectures" link at the top of the result page.

The title should be descriptive and as short as possible. The refinement links might be truncated to save space, particularly if the search results page has many refinement links.

You could also use the term $q, which shows the user's query as the refinement link. For example, if your user searches for "bacon", the refinement link will also be "bacon".

Label name The name of the refinement label. You use this name to tag sites in the annotations file.

In addition, Custom Search appends the label name to the queries of your users after they click a refinement link. If you were to look back at the Overview section, the sample search results page show a search box with "pimple more:condition_treatment". The "more:condition_treatment" part indicates use of a label, and "condition_treatment" is the value of the Label element's name attribute.

A descriptive name for your label. When you look at your annotations file, it would be good for you to be able to discern the purpose of the labels without having to refer back to the context files.

You must follow the naming convention, which includes the following:

  • Use only lowercase characters.
  • Replace punctuation and conjunctions (such as "and", "/", and "or") with underscore ("_"). For example, the phrase "warnings and recalls" should take the form of "warnings_recalls" and the phrase, "tests/procedures", "tests_procedures".
  • Keep the name short.
mode Modes in search engine labels and refinement labels work in the same manner.

You can create all three types—boost, filter, and eliminate refinements—in the same search engine.

For more detailed documentation about how weights work, see the Changing the Ranking of Your Search Results page.

Specify a mode value for each label:
  • BOOST- When users click the refinement link, sites tagged with the label are prioritized over other results with no labels.
  • FILTER- When users click the refinement link, only sites tagged with the label are shown. All other sites are excluded.
  • ELIMINATE - When users click the refinement link, sites tagged with this label are excluded entirely. Such labels do not need weights.

    Eliminate refinements are quite useful if you want to tell Custom Search to display relevant results except for ones that are tagged with that label. For example, you might want to let your vegetarian users to exclude meat-related sites when they are searching for cooking recipes.

  • Make titles of your refinement links clear. In the preceding example, a good title might be "vegetarian" or "remove meat".
weight Weights in search engine labels and refinement labels work in the same manner. For more detailed documentation about how weights works, see the Changing the Ranking of Your Search Results page. For boost and filter labels only. Any value between -1.0 and + 1.0. If you do not define the value, the label has an implicit value of +0.7. Although you can apply a wide range of weights to a label, it is better to apply a high weight to promote the refined results.

If you want to refine the search results to show only certain sites, use a weight close or equal to +1.0.

If you want to use negative weights with filter labels, you might have empty results. Filter labels restrict the search to a limited number of sites, and a weight of -1.0 excludes them altogether. Your users might be befuddled to see a refinement link that gives empty results.

Back to top

Removing the Effect of Search Engine Labels

If a site has search engine labels, the search engine label and the refinement label can interact and affect the results. If you want the refinement label to be the only one in effect, you can use a child element of Label, IgnoreBackgroundLabels, with true as its content. This technique is useful when you want the refinement to present a point of view that is different from the rest of the custom search engine.

The following example creates a refinement label specifying that when its refinement link is selected, the results page should display only sites tagged with this label. All search engine labels will be disregarded. 

     <Facet>
       <FacetItem title="Reference">
         <Label name="reference" mode="FILTER" weight="+1.0">
            <IgnoreBackgroundLabels>true</IgnoreBackgroundLabels>
         </Label>
       </FacetItem>
     </Facet>

Tagging Sites with Labels

You can tag sites with refinement labels. Each annotation can have multiple labels, which means that the same site can be used in other search engines and be ranked differently. The scores you apply to annotations to modulate the search engine labels also apply to the refinement labels.

XML Annotations

The following shows how you can tag sites with labels in XML format. 

<Annotations>
  <Annotation about="webcast.berkeley.edu/*" score="1">
    <Label name="university_boost_highest"/>
    <Label name="lectures"/>
  </Annotation>

  <Annotation about="www.youtube.com/ucberkeley/*" score="1">
    <Label name="university_boost_highest"/>
    <Label name="videos_boost_mid"/>
    <Label name="lectures"/>
  </Annotation>
</Annotations>

Back to top

TSV Annotations

The following shows how you can tag sites with labels in TSV format. 

URL        Label        Label        Label        Score        Comment        A=Date
www.cancer.gov/cancertopics/types/liver/*        _cse_Ansi-stoubiq  symptoms      This labels this url as symptoms.  20060504
www.medicinenet.com/liver_cancer/*        _cse_Ansi-stoubiq  symptoms    1.0  This labels this url as symptoms.  20060504
www.webmd.com/hw/cancer/*        _cse_Ansi-stoubiq  symptoms  for_patients  1.0  This is a great site for patients!  20060504
www.oncologychannel.com/*/treatment        _cse_Ansi-stoubiq  treatment          20060504

www.sirweb.org/*Treatments        _cse_Ansi-stoubiq  treatment    0.7    20060504

Taking the Next Step

In addition to creating refinement labels, you can also create other tools that help your users. Custom Search has various features that work on the queries of your users and help them get the results they are looking for faster.

 

< Back to Changing the Ranking of Your Search Results | Forward to Improving User Queries for More Relevant Results