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


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.

Results page
displays two 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:

  <Promotion id="1"
    queries="wanderer, the wanderer"
    title="Groo the Wanderer"
    description="Comedy. American series illustrated by Sergio Aragonés."
    image_url="" />
  <Promotion id="2"
    title="Dining guide: $q"
    enabled="true" />
  <Promotion id="3"
    title="Postalcode lookup: $q"
    description="Get the postalcode information quickly" />
  <Promotion id="4"
    title="iphone 4 or iphone 4s"
    enabled="true" />

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:

  <Promotion id="AmericanGraphics0001"
    queries="american born chinese, American Born Chinese, abc, ABC"
    title="American Born Chinese"
    description="Graphic novel. First-person account of growing up Asian
    American by Gene Luen Yang."
    image_url="" />

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

Attribute Description Value

Optional. A unique identifier for the promotion. If you don't use this attribute, Programmable Search Engine will create an ID for the promotion.

If you do not identify the promotion by its ID, each upload becomes additive; that is, each time you upload a modified file, you are adding new promotions, not replacing the existing ones. Promotions that have not changed at all will not be added as duplicates; but if you change a single character in a promotion, it is added as a new one. If you want to replace promotions with updated ones, you must delete them first.

You can use up to 40 alphanumeric characters, including underscores ( _ ).

Defines the search terms that users need to type in the search box to trigger the promotion.

To trigger a result, the search term from the user must exactly match the query term (unless your promotion uses regular expressions, in which case an exact match is not required). For example, if you created a query term for "badminton," and your user searches for "badminton games," your promotion will not appear. You have to create a query term for "badminton games" and other possible variants.

You can have multiple query terms with up to 100 characters each. Each term should be separated by a comma. The collective number of characters across all terms in a query set may not exceed 500.

The title of the promotion is also a link.

The title can have up to 160 characters. To update the promotion title with the contents of a user query, add $q, like this: Postal Code Lookup: $q. If a user query for 98102 triggers this promotion, Programmable Search Engine will replace $q with the user's query, and display the promotion title like this: Postal Code Lookup: 98102.


The hyperlink used by the title. It also appears as a link at the bottom of the promotion.

The URL of the webpage to which you want to direct your users. To update the URL with the contents of a user query, add $q, like this:$q. If a user query for 98102 triggers a promotion, Programmable Search Engine will display the host name of the URL as normal (, but clicking the URL will take the user to

Optional. Description for the promotion.

HTML tags are interpreted as plain text, not formatting instructions.

The description can have up to 200 characters.

Optional. An icon or image for your promotion. The image can from anywhere on the web. It can be in .gif, .jpeg, and .png formats.

The 40x40-pixel image is also a link. When your users click it, they are sent to the web address you have defined.

The URL of the image you want to highlight.

Optional. If true, all query input (including commas) will be treated as a single regular expression. For example, pizza \d{5,5} will match any 5-digit postal code queries preceded by the string "pizza", like "pizza 98102".

Default value is false.

Optional. Indicates whether the promotion is currently live.

Allowed values are true or false. If not set, the default value is true.