Creating Special Results

The Improving User Queries for More Relevant Results page showed you how you can improve the queries of your users to get better search results. This page shows you how you can create special results that appear at the top of result pages when your users search for certain queries. It assumes that you are familiar with context and annotations files.

Contents

This page includes the following sections:

• Overview
• Choosing the Type of Special Result
• Following Best Practices
• Creating Promotions
• Creating Subscribed Links
• Taking the Next Step

Overview

If a webpage has few other webpages linking to it or is not deemed relevant enough by the Google search algorithm, it appears further down in the results. (If the webpage has not yet been indexed, it will not appear at all in the search results. To learn more about fixing missing results, see the Selecting Sites to Search page.) If tweaking the ranking of the search results and improving the queries issued by your users still do not get the search results that you want, you can create special results that you associate with queries.

These special results enable you to create custom results that directly answer the queries of your users, direct them to important information, or point them to webpages that are not at the top of the results page yet are especially relevant. They also let you define the query terms that trigger the results you created. The two types of special results are:

• Promotions - simple results with links to relevant webpages. For example, if you want the webpage on badminton to be displayed at the top of the results page when your users search for "feisty sports", you can create a promotion for the badminton page.
• Subscribed links - result snippets for a set of queries. Subscribed Links directly answers your users' questions and save them from some research work. For example, if you want to answer questions about the fastest badminton smash on record, you can create a subscribed link that responds with "332 km/h". You can even create another subscribed link that converts km/h to mph, thus letting your users learn that 332 km/hr is 206 mph.

Choosing the Type of Special Result

Before you start creating special results, determine which type best suits your needs. Promotions are simpler and easier to create, while subscribed links have richer features but require significantly more planning, development, and troubleshooting. Both types of special results involve creating the query terms for triggering special results as well as the content of the results.

We recommend that you use promotions, unless you are certain that the richer feature set of subscribed links is a better fit for the needs of your users.

Use the following table to pick the appropriate format:

Following Best Practices

If your results are neither useful nor relevant, they end up feeling like spam to your users. Here are a few tips:

• Don't create special results with large numbers of triggering queries that are only tangentially related to the results.

  Let's say you are creating a special result that highlights howler monkeys in your search engine about disastrous pets. You might create queries that include "monkey", "primate", and "simian." Each time your users enter one of the queries you defined, they will see the special result about howler monkeys appear in their search results page. Now, if you start adding "jungle" and "zoo" to your list of triggering queries for your special result on howler monkeys, your users–who are probably looking for information about places, not monkeys–will be baffled by your seemingly random results about howler monkeys.

• Research the results that a search term retrieves, and formulate your query term accordingly.

  If a search term already retrieves the kind of results that you want, you don't need to create a special result for it. For example, the straightforward search for "Groo", a comic book character, yields highly relevant results about Groo the Wanderer. So it's redundant to create a special result for that. On the other hand, the search term the Wanderer does not retrieve results about Groo the Wanderer at the top of the results page. That term is a better candidate for special results.

For more guidelines on Subscribed Links, see its developer guide.

Creating Promotions

A promotion is simply an association between a pre-defined set of query terms and a link to a webpage. When a user types a search that exactly matches one of your query terms, the promotion appears at the top of the page. This feature is particularly useful for directing users to webpages that are further down in the results list than you would like because the webpages have not yet been indexed, have very few links to them, or are not deemed by Google's search algorithm to be directly relevant. It is also useful for making announcements and promoting products, services, events, and content that you want your users to discover.

Figure 1: Searching for "wanderer" in the search engine for Comics triggers promotions.

Back to top

Creating the Promotions File

Unlike other Custom Search features, you create the XML for promotions not in the context file nor the annotations file, but in its own file. As with any XML file, you can use a simple text editor to create and edit the promotions file. Just save the text file with the file extension .xml (for example, cse_promo_badminton.xml).

The following code describes promotions for a search engine on comic books:

<Promotions>
     <Promotion id="1" 
                queries="wanderer, the wanderer" 
                title="Groo the Wanderer" 
                url="http://www.groo.com/"
                description="Comedy. American series illustrated by Sergio Aragonés."
                image_url="http://www.newsfromme.com/images5/groo11.jpg" />
     <Promotion id="2" 
                queries="gaul,the gaul" 
                title="The Adventures of Asterix" 
                url="http://www.asterix.com/"
                description="Comedy. French series illustrated by Albert Uderzo." />
     <Promotion id="3" 
                queries="wanderer, the wanderer" 
                title="Join the Groo the Wanderer Groop" 
                url="http://www.groo.com/groop.html" />
</Promotions>

A promotions file has one element and one child element that can have multiple siblings, as described in the following hierarchy:

• Promotions (1 only)
  • Promotion (multiple siblings allowed)

Note: The second-level Promotion tags are different from the top-level Promotions tags in that they take the singular form; that is, there is no "s" after "Promotion").

You can have up to 2,000 promotions in your account. You can allocate the promotions across the search engines in your account any way you like. Let's say you have two search engines in your account. You can apportion 2,000 promotions to one search engine and nothing to the other; or you can apportion up to 1,000 promotions to each search engine.

You can upload multiple promotions files for a search engine. An account can have up to 4 MB of promotions files, with each file being as large as 500 KB.

Back to top

The Attributes of the Promotion Element

All attributes except id, description, and image_url are required.

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

<Promotions>      
   <Promotion id="AmericanGraphics0001"
              queries="american born chinese, American Born Chinese, abc, ABC" 
              title="American Born Chinese" 
              url="http://books.google.com/books?id=vawdZyrDw64C&dq=american+born+Chinese+gene+yang"
              description="Graphic novel. First-person account of growing up Asian American by Gene Luen Yang."
              image_url="http://146.74.224.231/archives/Gene%20Yang.jpg" />
</Promotions>

The following table lists the attributes of Promotion and their values.

Creating Subscribed Links

You can kick up the search-engine customization a notch with Subscribed Links, which lets you create result snippets for a set of queries. It can directly answer your users' questions and save them from some research work.

For instance, users who want to search for basic information about the comic character Asterix might go through the following steps: type the search query in the search box, look through the search results to find the most promising website, click the link to the relevant website, wait for the website to load, and—finally—skim the page for the piece of pertinent information. However, if the custom search engine has a subscribed link for comic characters, users can just type "asterix" in the search box and immediately get the information that they seek. They do not have to scroll down or click anything else to get the answers to their queries.

Figure 2: Searching for "asterix" in the Comics search engine triggers a subscribed links result.

If you are familiar with Subscribed Links, you might notice that the subscribed link result in the Custom Search results page looks different from subscribed link results in Google search.

You could add subscribed links created by other developers or you could create one yourself using the Subscribed Links wizard or API. To see what kinds of subscribed links are available, check out the Subscribed Links Directory; to learn more about creating subscribed links, read the Google Subscribed Links Developer Guide.

Back to top

Enabling Subscribed Links

If you have created and tested your subscribed links, you can integrate them into your search engine by either of the following methods:

• Using the control panel - for quickly enabling the subscribed links you created under the same account as the custom search engine.
• Using the context file - for enabling subscribed links created by one or more third-party developers (including subscribed links you created under an account different from your custom search engine account).

Using the Control Panel

To enable the subscribed links you created using the control panel:

1. Go to the Basics tab.
2. Select the Enable special results, such as subscribed links and promotions check box.
3. Click Save Changes.

Using the context file

To enable subscribed links using XML, create the Subscribed Links section of the context file as described in the following:

1. Start the Subscribed Links section by creating <SubscribedLinks> and </SubscribedLinks> tags inside the CustomSearchEngine tags.
2. Create the child element, SubscribedLink, and define its creator attribute with the creator ID of the subscribed link, as in the following.

   <SubscribedLink creator="017771777217723414381"/>

   Note: The second-level SubscribedLink tags are different from the top-level SubscribedLinks tags in that they take the singular form; that is, there is no "s" after "SubscribedLink".

   To find the creator ID, see the Finding the Creator ID section.

The following example shows a search engine that uses subscribed links.

<CustomSearchEngine volunteers="false">
   <Title>...</Title>
   <Description>...</Description>
   <Context>...</Context>
   <SubscribedLinks>
     <SubscribedLink creator="017771777217723414381"/>    
   </SubscribedLinks>
</CustomSearchEngine>

As the example shows, Subscribed Links elements have the following structure:

• CustomSearchEngine
  • SubscribedLinks (1 only)
    • SubscribedLink creator (multiple siblings allowed)

Adding Multiple Third-Party Subscribed Links

You can associate multiple Subscribed Links accounts—including ones created by other developers—with your search engine. All you need is the creator ID of the subscribed links. You can look through the Subscribed Links Directory and integrate relevant subscribed links into your results page.

The following example shows a search engine that uses subscribed links from two different developers.

<CustomSearchEngine volunteers="false">
   <Title>...</Title>
   <Description>...</Description>
   <Context>...</Context>
   <SubscribedLinks>
     <SubscribedLink creator="017771777217723414381"/>
     <SubscribedLink creator="000455946290257563395"/>
   </SubscribedLinks>
</CustomSearchEngine>

While you can integrate multiple subscribed links to your search engine, your results page will display no more than three subscribed links for each query.

Finding the Creator ID

To find your own creator ID:

1. Download the context file generated by the control panel. For instructions, see The Basics page.
2. Find the creator attribute of the CustomSearchEngine element.

   The string value of the attribute is the creator ID. For example, in the element, <CustomSearchEngine id="hhuyevoygck" creator="001001001001001001234" volunteers="false"... " encoding="UTF-8">, the creator ID is: 001001001001001001234.

You can also programmatically retrieve the creator ID using the API.

To find the creator ID of a third-party developer:

1. Go to the Subscribed Links Directory.
2. Click the title of the subscribed link to get to its profile page.
3. Copy the the creator ID from the URL.

   The ID is the numerical value that comes after user= parameter. For example, the Merriam-Webster Online profile page has the following URL: http://www.google.com/coop/profile?user=001435137662681742633. The creator ID for Merriam-Webster Online is 001435137662681742633.

Back to top

Taking the Next Step

When you are done creating tools for your search engine, you can start designing its look and feel.

< Back to Improving User Queries for More Relevant Results | Forward to Designing the Look and Feel >