This page describes how to change or respond to your users' queries to deliver search results that are more relevant or that suit your site's requirements.
This page includes the following sections:
- Appending Search Queries with Refinement Labels
- Redirecting Search Queries with Refinement Labels
- Expanding Search Queries with Synonyms
- Autocompleting Queries
If you know your audience well, you can roughly predict the kinds of things they might search for. You can anticipate their queries and help them find more relevant results.
Custom Search enables you append search terms to your users' queries, redirect users to another website or search engine, and create synonyms of your users' queries. The first two features are implemented through refinements, which your users can apply or ignore; while the synonym features act on your users' queries without requiring any user action.
Appending Search Queries with Refinement Labels
To provide refinement links that add helpful search terms to user queries, use the
Rewrite element in the Custom Search XML annotations file. The element appends the search terms to your users' queries when they click a refinement link. The
Rewrite element can have up to 100 characters, all of which should be lowercase, except for uppercase search operators such as
OR. To learn more about search operators, see Advanced Search Made Easy. To learn more about refinements, see Refining Searches.
The following example shows you how you can use
<CustomSearchEngine> <Title>Universities</Title> <Context> <Facet> <FacetItem title="Homework"> <Label name="assignments" mode="BOOST"> <Rewrite>homework OR assignment</Rewrite> </Label> </FacetItem> </Facet> </Context> </CustomSearchEngine>
The example shows how to help users who click the refinement link called "Homework". It appends the additional search terms "homework" and "assignment" to the search query that your users type.
A refinements with the
Rewrite element has the following structure:
FacetItem(up to four)
Redirecting Search Queries with Refinement Labels
To redirect your users to a different website when they click on a refinement link, use the
url attribute, as follows:
<CustomSearchEngine> <Title>Universities</Title> <Context> <Facet> <FacetItem title="Papers"> <Label name="papers" mode="FILTER"/> <Redirect url="http://scholar.google.com/scholar?q=$q"/> </FacetItem> </Facet> </Context> </CustomSearchEngine>
This example redirects 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 last part,
$q, specifies your user query.
If your URL has CGI arguments, use
& instead of
A refinement with the
Redirect element has the following structure:
FacetItem(up to four)
Redirect is a child element of
Expanding Search Queries with Synonyms
You can expand your users' search queries by using synonyms, which are variants of a search term. For example, the finance-related search query,"interest", could have the following equivalent alternatives: "yield", "dividend", "coupon", and so on. If you create synonyms for "interest" in your financial search engine, your users will not need to type multiple variants to find information they are seeking. The custom search engine will automatically search for all sites that are relevant to "interest", "yield", "dividend","coupon", and other related terms.
A search term with synonyms you defined automatically triggers a search expansion, whether or not the user enters the search term on its own or along with a series of other words. Let's say you've defined "ninja" as a search term with the synonym variant, "assassin". Any search query that includes the word "ninja"—such as just "ninja" alone or "ninja hotdog eating contest"—would expand the query to include the synonymous variants. It is as though the user had searched for "ninja OR assassin" or "ninja OR assassin hotdog eating contest".
Popular query terms, common acronyms (such as "CD" for "certificate of deposit"), and familiar abbreviations (such as "munis" for "municipal bonds") that are idiosyncratic to your specialized field or interest are great candidates for having synonyms. If your search engine is popular enough and receives many searches for the same queries, you can get data about your most popular queries from the statistics page. Go to the Control Panel and for your search engine, and click the statistics link. Popular queries are listed at the bottom of the page.
You don't need to create synonyms for popular query terms. For example, the terms "UK", "Britain", "United Kingdom", "United Kingdom of Great Britain" are fairly well-known variants (if not technically synonyms) to most web users. Google already has a large body of synonyms for such terms, and you don't need to replicate this work. Instead, create synonyms for common terms that are specific to the interests of the users of your search engine. For example, in a financial search engine, "bond" would be a great candidate. Google may not know if users are looking for "James Bond", "chemical bond", "adhesive bond", or "emotional bond". You, on the other hand, know that they are looking for a financial instrument and can easily come up with synonyms such as "fixed-income security" and "issue".
If you cannot discern whether a term is common or idiosyncratic, you can test the term and its variants on Google search. Type the query term (such as "san francisco") on Google search and then open a new browser window. In the Google search box, type the query term, the search operator
OR, and the variant of the query term (for example, "san francisco OR sf"). Compare the two results pages. If they are exactly the same, then Google has the synonymous terms covered.
Unlike other Custom Search features, you create the XML for synonyms 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 synonyms file. Just save the text file with the file extension .xml (for example,
Here is an example of a synonyms file:
<Synonyms> <Synonym term="stock"> <Variant>equity</Variant> <Variant>share</Variant> </Synonym> <Synonym term="bond"> <Variant>fixed-income security</Variant> <Variant>issue</Variant> <Variant>high yield debt</Variant> </Synonym> </Synonyms>
A synonyms file has one element and one child element that can have multiple siblings, as described in the following hierarchy:
Synonym term(multiple siblings allowed)
Variant(up to 10 for each
You create the search term in the attribute value of the
Synonym child element and define each of its synonyms in the
Variant element. The search term and its synonym variants could be a single word (such as "cookie") or phrases (such as "buttermilk cookie" or "crying over spilled milk").
If you are programmatically uploading synonyms using HTTP methods, you have to use additional elements that tell the Custom Search API what to do with the synonyms, such as whether they should be added or removed. For more information, see Programmatically Creating Custom Search Engines.
The following table lists the limits for synonym files:
|Number of search terms (
||Multiple search terms, so long as the total number of variants do not exceed 500 for each search engine.|
|Number of variants (
|Total number of variants (
|Number of files||As many as you need, so long as the aggregate size of all files in the account does not exceed 4MB|
Autocompletion is a list of suggested queries that appear as users type in the search box.
Figure 1: Typing just a few characters in the search box brings up a drop-down list that provides options for different search queries.
The list of optional queries used for autocompletion is derived partly from the contents of the website and the popularity of the query term. However, you can customize autocompletion by adding or removing terms from it, either in the control panel or through a bulk upload in an XML file.
To enable autocompletion in search engines using the Custom Search Element:
- In the Control Panel, click the Autocompletions section.
- Select the Enable autocompletions check box.
- Click Save Changes.
- Click the Get code tab and copy the generated code snippet, and insert it your webpage.
You can add or remove individual terms in the Autocompletions section of the Control Panel or upload all the terms using an XML. The terms that you add appear above the algorithmically generated terms for all queries.
It might take up to 12 hours before autocompletion terms start appearing in your search engine.
To add or remove terms in bulk, upload an autcompletions XML file. As with any XML file, you can use a simple text editor to create and edit the synonyms file. Just save the text file with the file extension .xml (for example, cse_autocompletion_finance.xml).
Adding and Removing Autocompletion Terms
Here is an example of a autocompletions file that you can upload.
<Autocompletions> <Autocompletion term="cake" type="1" language=""/> <Autocompletion term="strawberry.*" type="2" match="2" language=""/> <Autocompletion term="vanilla" type="2" language=""/> <Autocompletion term="apple" type="3" language=""> <Promotion id="1" queries="dessert" title="Apple pie for dessert!" url="http://www.example.com/applepieforsale" start_date="" end_date="" image_url="" description="Apple pie is the best dessert ever!"/> <Promotion id="2" queries="apple" title="Buy Apple pie" url="http://www.example.com/applepieforsale" start_date="" end_date="" image_url="" description="We stock the best apple pie in the world, right here."/> </Autocompletion> </Autocompletions>
In the sample code, "apple" is included in the list of possible autocompletion terms, whereas "vanilla" and any term starting with "strawberry" will never be presented to the user as an autocompletion term. In addition, a promotion for the URL www.example.com/applepieforsale will appear whenever users search for "apple".
An autocompletion file has one element and one child element that can have multiple siblings, as described in the following hierarchy:
Autocompletion(multiple siblings allowed)
The following table lists the autocompletion attribute names.
||The individual term or regular expression to include or exclude.||Autocompletion term to include or exclude. For example, if you want to add
"storm shadow" to the list of autocompletion terms presented to your users, add
"storm shadow" as the value. Note that using the same term in multiple
||Specify whether the term should be included or excluded from the autocompletion.||Specify either:
||Optional. Specify whether you want the term to be matched exactly or with regular expression.||Specify either:
||Optional. Specify the language of the autocompletion.||Leave this undefined, because, by default, Custom Search uses the language you have defined on the Basics section of the Control Panel.|
To enable promotions in autocomplete, add the
The following table lists the Promotion attribute names. More information about promotions.
||A unique string identifier of the promotion to display in autocomplete.|
||A set of comma-separated user queries, any of which will trigger the promotion. For example, if queries are specified as
||The title of the promotion.|
||Optional. The date on which the promotion should first appear.|
||Optional. The last date on which the promotion should appear.|
||Optional. A URL pointing to the image to be displayed in the promotion.|
||Optional. A text description of the promotion.|