Promotions

This page describes how to create promotions 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. If you can program, and you want to customize the appearance of your result snippets, see Customizing Your Results Snippets.

1. Overview
2. Best Practices
3. Creating Promotions

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 Selecting Sites to Search.) 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 promotions that you associate with queries.

Promotions 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. 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.

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 promotions with large numbers of triggering queries that are only tangentially related to the results.

  Let's say you are creating a promotion 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 promotion 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 promotion 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 promotion 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 promotion 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 a promotion.

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

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, promo_badminton.xml).

The promotions file includes the contents of the promotions; but the context file controls the look and feel of the promotions. To learn more about controlling the appearance of your promotions, see Look and Feel.

The following code describes a set of promotions:

<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="pizza,burger,salad"
    title="Dining guide: $q"
    url="http://www.dining.com/$q"
    is_regex="false"
    enabled="true" />
  <Promotion id="3"
    queries="\d{5,5}"
    title="Postalcode lookup: $q"
    url="http://www.postalcode.com/$q"
    image_url="http://www.postalcode.com/icon.jpg"
    is_regex="true"
    enabled="true"
    description="Get the postalcode information quickly" />
  <Promotion id="4"
    queries="iphone(4|4s)"
    title="iphone 4 or iphone 4s"
    url="http://www.buyiphone.com"
    is_regex="true"
    enabled="true" />
</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)

You can have up to 2,000 promotions in each of your search engines. 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.