The Creating a Subscribed Link Using XML page showed you how you can create a subscribed link with XML. This page shows you how you can create large sets of queries that could trigger your custom results. But before you dive into creating a large body of queries, review the guidelines for queries first. Start conservatively. Create a small number of queries that are directly relevant to the result, then slowly expand your sets of queries. Don't clutter the Google result page of your users, lest they remove your subscribed link from their result page.
As you learned from the Creating a Subscribed Link Using XML page, the Query element in the XML file defines the query that triggers your subscribed link result. That's fine if your users type only that exact query. However, if they use synonyms or variants of the query, they're out of luck. Well, you could create another ResultSpec for each additional variant of the query, but that gets tedious and clunky in no time.
Fortunately, the Subscribed Links API lets you create query patterns, which are lists of synonyms and variants for your queries. It's easy to create a large query pattern, so don't get carried away and add queries that are just tangentially related to your results. The Subscribed Links API also provides a number of common object types that you can use in your query patterns. You do not need to create object types for cities, countries, dates and times. For more information, see Special Object Types.
To create query patterns for a custom result:
Instead of specifying literal text, define an object type–which is a variable for your query–in your Query element.
Define the pattern of queries for the variable you just created. This list of synonyms and variants of your query are defined in the DataObject elements.
Creating an Object Type for Your Query
To create a set of queries, use an object type in your Query element. An object type acts as a variable or a placeholder and its values are defined in DataObject elements.
Suppose you want to report the speed limits of various highways to your users, and you have determined that most queries take the form of "speed limit on X", where X is the name of a highway. Now if you are creating results for Highway 101, your code would look like this:
<ResultSpec id="HighwayMatch1">
<Query>speed limit on Highway 101</Query>
<Response>
<Output name="title">Speed limit info for US Route 101</Output>
<Output name="more_url">www.myspeedlimitssite.com/</Output>
<Output name="text1">The maximum speed limit for US Route 101</Output>
<Output name="text2">is 65 mph.</Output>
</Response>
</ResultSpec>
But if you want to create a query pattern, you would replace the static "Highway 101" in the Query element with an object type, which you could call [Highway]. Object type names are case-sensitive and they should always be enclosed in brackets ( [ ]).
<ResultSpec id="HighwayMatch1">
<Query>speed limit on [Highway]</Query>
<Response>
<Output name="title">Speed limit info for US Route 101</Output>
<Output name="more_url">www.myspeedlimitssite.com/</Output>
<Output name="text1">The maximum speed limit for US Route 101</Output>
<Output name="text2">is 65 mph.</Output>
</Response>
</ResultSpec>
The object type called [Highway] is inserted as a placeholder for the query patterns that will be defined next.
Defining the Query Pattern
After you have created the object type, expand the list of query variants in the DataObject element.
To define the query pattern:
Create the <DataObject></DataObject> tags right after the ResultSpec closing tag.
Define the id attribute of DataObject. The ID must be unique across all data objects and XML files.
Define the type attribute of DataObject. In the example, Highway is the type. It is the same type that is enclosed in brackets in the Query element of the ResultSpec (see the previous example).
Create and define the <QueryName value=""/> tags inside the DataObject element. QueryName lets you expand the number of possible queries for triggering custom results. A search that matches any of the QueryName values will trigger the subscribed link response.
The QueryName element must be unique across data objects. Even if your data objects are scattered across multiple files, you must maintain the uniqueness of the values of the the QueryName element.
You can have many QueryName child elements in one DataObject element, but you cannot have two DataObject elements of the same type have the same QueryName element.
You can also define variables in your response, which are described in greater detail in the Creating Response Templates page.
A DataObject for our Highway 101 example would look like this:
Now your users do not need to type "speed limit on highway 101" exactly in their queries. Any of their queries that include "speed limit on" and any variants for "highway 101" that you have defined in the query pattern will trigger the custom result for Highway 101.
Completing the Picture
Putting together the ResultSpec and the DataObject in the previous two sections gives an XML file like this:
<Results>
<AuthorInfo description="Highway speed limit" author="Your Name"/>
<ResultSpec id="HighwayMatch1">
<Query>speed limit on [Highway]</Query>
<Response>
<Output name="title">Speed limit info for US Route 101</Output>
<Output name="more_url">www.myspeedlimitssite.com/</Output>
<Output name="text1">The maximum speed limit for Highway 101 is 65 mph.</Output>
</Response>
</ResultSpec>
<DataObject id="Highway101" type="Highway">
<QueryName value="101"/>
<QueryName value="US 101"/>
<QueryName value="Highway 101"/>
<QueryName value="Route 101"/>
<QueryName value="US Route 101"/>
</DataObject>
</Results>
If you upload this file, a user who subscribes to your subscribed link will see a result like this:
This custom result appears when your users type any of the query variants you have defined in the query pattern. The search queries "speed limit on 101" or "speed limit on US 101" will trigger the result for Highway 101 because you have defined the search terms in your DataObject element. You can expand the number of queries that would trigger this result by defining more QueryName child elements in your DataObject element.
Creating Multiple Object Types and Data Objects
Your Query element can have more than one object type; it can be of the same type, or it can be of different types, so you can create queries such as: <Query> distance of [City] to [City]</Query> or <Query> [restaurant] in [City]</Query>. Incidentally, [City] is one of the special object types for which you do not need to create supporting data objects. For more information, see the Special Object Types page.
For your subscribed link to be useful, you should have more than one data object that answers only one search term. For example, the users of the Highway Speed Limit Subscribed Link would not be searching for the speed limit for Highway 101 alone. They would also be searching for the speed limits of other highways, such as Highway 880 or Highway 580. So to answer their queries, the subscribed link must have a data object for each highway. Of course, the corresponding custom result should be relevant to the different search terms, so having fixed text in the Response element of the ResultSpec element does not make sense. (The sample code in the previous section has fixed text that can only answer search queries on Highway 101.) This is why the Subscribed Links API also has variables for the Response element (called "attributes"), and their values are also defined in the DataObject elements. So the data object for, say, Highway 280 contains query variants for "Highway 280" and response values related to that Highway 280. The next page, >Creating Response Templates, discusses attributes in detail.
Re-arranging Keywords in the Queries
You can expand your set of triggering queries further by swapping keywords, as well as including or omitting prepositions, articles, and other common words. For example, you can create multiple ResultSpec elements with Query elements such as the following:
speed limit on [Highway]
the speed limit on [Highway]
maximum speed limit of [Highway]
[Highway] speed limit
A subscribed link file can have more than one ResultSpec element, but each ResultSpec element can have only one Query and one Response child elements. So you need to create another ResultSpec for each query that you add.
Using Regular Expressions
Yet another technique for expanding your set of triggering queries involves Perl-compatible regular expressions (PCRE). A regular expression is a special pattern of characters for describing searches and manipulating text. For example, if you want to search for "monkey " or "monkeys" in a text file, you could use the question mark (?) regular expression, which indicates that the character immediately preceding the regular expression could either exist or not. If you type "monkeys?" in a search tool that can process regular expressions, it will find any instance of "monkeys" and "monkey".
This section assumes that you are already familiar with regular-expression concepts and patterns. So if the previous paragraph does not sound familiar to you, you might want to read tutorials, reference materials, or websites that discuss regular expressions in detail.
To use regular expression inside your search query, observe the following rules:
Specify regular expressions to match in a query by prefixing it with RE: and enclosing the regular expressions in brackets ([ ]) like in the following examples:
<Query>[RE:(?i)howler monkeys?]</Query>
<Query>howler [RE:(?i)monkeys?]</Query>
<Query>howler monkey[RE:(?i)s?]</Query>
Use no more than 1,000 characters and 16 match groups. While the limitation is fairly large, you should take care to make sure that your regular expressions are efficient. Poorly written regular expressions can slow down evaluation. In fact, inefficient regular expression can cause the matching process to time out and prevent Google from displaying your results.
If you want to include a backslash (\) in your regular expression, you must use the escape character, which also happens to be a backslash. So a backslash in a regular expression should be written as "\\".
Unlike other types of query matching, regular expression matching is case-sensitive. This was designed for your users, who might want case-sensitive matching for parts of their queries. If you want Subscribed Links to match regular expressions without regarding capitalization, simply prefix the regular expression with (?i). For example:
<Query>[RE:(?i)(grey|gray)] monkey</Query>.
In some situations, you need greedy matching to make sure that the Subscribed Links matcher always consumes the longest possible matching portion of the query. The matcher goes through each term in the query, including the regular expression, in a left-to-right order and triggers a custom result only if the entire query is matched.
For example, the regular expression bagels? matches either "bagel" or "bagels", while the alternative, bagel|bagels will always match "bagel" while leaving the longer string, "bagels", unmatched. True, bagel|bagels returns a partial match for the string "bagels" in the regular expression processor, but it doesn't consume the last "s". Therefore, since the Subscribed Links matcher requires that the whole query be consumed to get a valid match, <Query>[RE:(bagel|bagels)]</Query> will not trigger a custom result for the query "bagels".
Be careful when using a regular expression that matches any word or any set of words at the end of your query. For example, the following query triggers results on any search query that starts with the name of a city followed by the word "elevation" and any other word or set of words:
<Query>[City] elevation [RE:(.*)]</Query>
The intent behind this regular expression is to trigger results on any search query that begins with the keywords (which, in this case, is a city name, such as "Beijing" and "elevation"), even if the search query contains other words. This regular expression triggers custom results that the user might not want. Usually, users add additional words to their search queries to refine their search. So the "extra words" that you want your subscribed link to ignore could be words that indicate that the user is looking for something completely different from the content that your results provide. This false triggering happens more with generic or ambiguous keywords, such as "apple", which can refer to either the fruit or the computer company.
