# Refining Searches 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. 1. [Overview](https://developers.google.com/custom-search/docs/refinements#overview) 2. [Creating Refinement Labels](https://developers.google.com/custom-search/docs/refinements#create) 3. [Tagging Sites with Labels](https://developers.google.com/custom-search/docs/refinements#tag) 4. [Controlling the Number of Displayed Refinement Labels](https://developers.google.com/custom-search/docs/refinements#shown) ## 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. ![Search results page with a selection of refinement links](https://developers.google.com/static/custom-search/images/refinements.png) 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](https://developers.google.com/custom-search/docs/refinements#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 [Programmable Search XML annotations file](https://developers.google.com/custom-search/docs/annotations). 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. ``` Universities ``` The `Facet` element has the following structure: - `Facet ` - `https://developers.google.com/custom-search/docs/refinements#elements` - `https://developers.google.com/custom-search/docs/refinements#elements` - `https://developers.google.com/custom-search/docs/queries#rewrite` - `https://developers.google.com/custom-search/docs/queries#redirect` Each `Facet` elements can have up to four `FacetItem` child elements. You can create as many refinement labels as you want. You can also control [how many labels appear on search results pages](https://developers.google.com/custom-search/docs/refinements#shown). [Back to top](https://developers.google.com/custom-search/docs/refinements#top) ### Example: Refinement Labels A basic refinement labels look like the following: ``` ``` **Figure 3:** The sample code produces a search results page with a label. ![Search results page with a refinement link called Lectures](https://developers.google.com/static/custom-search/images/refine_basiclabel.png) [Back to top](https://developers.google.com/custom-search/docs/refinements#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 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 `$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, Programmable Search Engine 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](https://developers.google.com/custom-search/docs/refinements#overview), 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. | | `Label` | `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 [Ranking Search Results](https://developers.google.com/custom-search/docs/ranking#mode) 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 Programmable Search Engines 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". | | `Label` | `weight` | 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](https://developers.google.com/custom-search/docs/ranking#weight). | *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 confused by a refinement link that gives empty results. | [Back to top](https://developers.google.com/custom-search/docs/refinements#top) ## 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. ``` ``` [Back to top](https://developers.google.com/custom-search/docs/refinements#top) ## 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 `Rewrite` element. 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. Uppercase search operators such as `OR` are the only exceptions. To learn more about search operators, see [Advanced Search Made Easy](http://www.google.com/help/refinesearch.html#or). The following example shows you how you can use `Rewrite`. ``` ``` 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. [Back to top](https://developers.google.com/custom-search/docs/refinements#top) ## Controlling the Number of Displayed Refinement Labels If you have defined refinements, Programmable Search Engine 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. If you choose to display only a subset of refinement labels, Programmable Search Engine displays the refinement labels with the largest number of search results. For example, if you have three refinement labels called "HTML," "CSS," and "JavaScript," but set your search engine to display only two, Programmable Search Engine displays the two refinement labels with the largest number of results for the specific user query. 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 `CustomSearchEngine` tag. ``` ```
Where `n` is the number of refinements you want to show.
Setting the number to `0` shows no refinement label with search result. Without 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](http://support.google.com/programmable-search/bin/answer.py?answer=70359) page of the Control Panel. [Back to top](https://developers.google.com/custom-search/docs/refinements#top)