This page describes how to help your users refine their search queries using refinement labels. Unlike search engine labels, refinement labels are visible to your users, and appear at the top of the search results page.
- Creating Refinement Labels
- Tagging Sites with Labels
- Controlling the Number of Displayed Refinement Labels
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.
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.
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
<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>
Facet element has the following structure:
Facet elements can have up to four
child elements. You can create as many refinement labels as you want. You can
also control how many labels appear on search results pages
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.
Elements of Refinement Labels
The following are the child elements of
||The refinement link that is displayed at the top of the results page.||
The title of the link. In the example above, that is "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
||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
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:
||Modes in search engine labels and refinement labels work in the same
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 Ranking Search Results page.
||Weights in search engine labels and refinement labels work in the same manner. For more detailed documentation about how weights works, see Ranking Search Results.||For boost and filter labels only. Any value between
If you want to refine the search results to show only certain sites,
use a weight close or equal to
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
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
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.
Note: This refinement only works for the free standard edition of Custom Search and is not supported in Google Site Search. Adding this label to your Google Site Search will result in a 403 error when users apply this refinement.
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.
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>
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
Other Ways to Help Your Users
Besides refining search results, you can use refinement links to help your users get more targeted results. You can append search terms to your users' queries or redirect your users to a different search engine or website.
Appending Search Queries
If you would like to help your users by adding helpful search terms to their
queries, you can use the
The element appends the search terms to your users'
queries when they click a refinement link. The
can have up to 100 characters, all of which should be lowercase. Uppercase
search operators such as
OR are the only exceptions. To learn more
about search operators, see
The following example shows you how you can use
<Facet> <FacetItem title="Homework"> <Label name="assignments" mode="BOOST"> <Rewrite>homework OR assignment OR assignments</Rewrite> </Label> </FacetItem> </Facet>
The example shows how to help users who click the refinement link called "Homework". It adds the words, "homework", "assignment", or "assignments" to the search queries that your users typed.
Redirecting Search Queries
To redirect your users to a different website when they click on a refinement
link, use the
Redirect is a child element of
<Facet> <FacetItem title="Papers"> <Label name="papers" mode="FILTER"/> <Redirect url="http://scholar.google.com/scholar?q=$q"/> </FacetItem> </Facet>
This example directs users to another search engine,
http://scholar.google.com/scholar. The latter part of the URL,
?q=, is the parameter for entering queries for Google Scholar. The
parameter value in the last part,
$q echoes your users' queries.
If your URL has CGI arguments, use
& instead of
Controlling the Number of Displayed Refinement Labels
If you have defined refinements, Custom Search displays the refinement labels at the top of the search results. You have the option of showing either all of the refinement labels or just a subset of them.
This means that although the number of refinement labels that are displayed are fixed, the refinement labels themselves change according to the query of the user.
To set the number of refinement labels in the XML definition, add a
top_refinements attribute to your context definition's
nis the number of refinements you want to show.
Setting the number to
0 shows no refinement label with search
the setting in context definition, your search engine displays all
refinement labels you have defined for any user query, regardless if any
search result for those labels.
You can also set the number of refinement labels on the Refinements page of the Control Panel.