The Creating Patterns of Queries page discussed a number of ways to create advanced queries. This page tells you how you can create more powerful and flexible responses to the queries.
As you learned in the Creating Patterns of Queries page, you can use object types and data objects to create query patterns. An object type acts as a variable in your Query element, and its values are defined in the DataObject element. This structure allows you to have relatively few core ResultSpec elements, because the long lists of query variants and synonyms are housed in separate DataObject elements. You, therefore, don't have to create duplicative ResultSpec elements with different query variants.
Likewise, you can use variables called attributes for your Response element. Just like object types for Query elements, the values of attribute variables are defined in the DataObject element. By using variables in your response, you can create a template for your custom results.
Let's expound on the example in the Creating Patterns of Queries page. If you want to report the speed limits of various highways to your subscribers, the response you create for Highway 101 could have the following code:
<ResultSpec id="HighwayMatch1">
<Query>speed limit on [Highway]</Query>
<Response>
<Output name="title">Speed limit info for Highway 101</Output>
<Output name="more_url">www.myspeedlimitssite.com/describe?hwy=101</Output>
<Output name="text1">The maximum speed limit for Highway 101 is 65 mph.</Output>
</Response>
</ResultSpec>
The problem with the code is that the literal text is good for only one custom result—the result for Highway 101. If you want to cover many highways in the United States, you will be spending a lot of your time creating a result specification for each highway. However, if you create a response template with attribute variables, you can have a core text that is fixed and a few words that would change based on the search queries of your users.
To create a template for your response:
Specify the literal text for your custom result in the Response element.
Even though response templates are handy, you do not need to create them all the time, not even when the ResultSpec element already has an associated DataObject element with QueryName child elements. A ResultSpec element does require a complete pair of Query and Response child elements, but a DataObject element can have only QueryName elements. Sometimes, you might want a response with fixed text and no attribute variable. Perhaps the response for the search query is simple enough, or perhaps the response comes in a form of a gadget. In either case, you can just create a query with object types, and their associated data objects would contain only query patterns.
The Subscribed Links API provides a number of common object types and their corresponding attributes. You do not need to create object types and attributes for cities, countries, dates and times. For more information, see the Special Object Types page.
Creating Attribute Variables for Your Response
To create a response template, construct the output text in the Response element as described in the Creating a Subscribed Link Using XML page. Then insert attribute variables, which act as placeholders. Attribute variables are case-sensitive, must always be enclosed in brackets ( [ ]), and must be prefixed by object identifiers. An object identifier is a number that you attach in front of the attribute variable name to indicate which object type it is referring to. The identifier starts from zero (0).
The following example creates a template from the result specifications for Highway 101.
<ResultSpec id="HighwayMatch1">
<Query>speed limit on [Highway]</Query>
<Response>
<Output name="title">Speed limit info for [0.fullname]</Output>
<Output name="more_url">www.myspeedlimitssite.com/describe?hwy=[0.abbrev]</Output>
<Output name="text1">The maximum speed limit on [0.fullname]</Output>
<Output name="text2">is [0.max_speed_limit].</Output>
</Response>
</ResultSpec>
In the example, note the 0 in front of the attribute variables. The first object type in the Query element is [Highway], so attribute variables that refer to it should have 0 in front of their names. Hence, [0.fullname], [0.abbrev], and [0.max_speed_limit] in the Response element are attributes variables of the first object type. If there were a second and third object type, their attribute variables would be prefixed with 1. and 2., respectively. In other words, [1.attribute]indicates that the attribute variable refers to the second object type; and [2.attribute], the third. If your Query element has multiples of the same object type, you cannot use the same identifier. For example, a query constructed as distance between [City] and [City] will match two city names. When you construct the response, the first [City] in the query is object 0 and the second [City]is object 1.
Since we have created a response template, we do not need to create ResultSpec elements for highways 280, 880, 580, 80, and so on. The values of the attribute variables inserted in the static text are defined in various data objects.
Defining the Attribute Values
After you have created the response with attribute variables, define the attribute values in the appropriate DataObject element. Each data object is associated with a specific query-response pair. For example, the Highway Speed Limit subscribed link has a data object for each highway: one for Highway 280, another for 880, and so on. Presumably, you have already created the DataObject elements when you created the object type and defined the query patterns. So define the attribute values in the appropriate DataObject element.
To define the attribute values, create and define the <Attribute name="" value=""/> tag. The name attribute specifies the attribute variable that you want to define. The value attribute defines the value for the attribute variable. You do not need to—but it would make life easier—if you add the <Attribute> tags after the <QueryName> tags. A search that matches any of the QueryName values will trigger the Google to display custom results populated with the relevant attribute values.
A DataObject for the Highway 101 example would look like this:
Putting together the ResultSpec section and the DataObject section in our previous examples gives an XML file like this:
<Results>
<AuthorInfo description="Highway speed limit" author="Ada Bogart"/>
<ResultSpec id="HighwayMatch1">
<Query>speed limit on [Highway]</Query>
<Response>
<Output name="title">Speed limit info for [0.fullname]</Output>
<Output name="more_url">www.myspeedlimitssite.com/describe?hwy=[0.abbrev]</Output>
<Output name="text1">The maximum speed limit on [0.fullname]</Output>
<Output name="text2">is [0.max_speed_limit].</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"/>
<Attribute name="fullname" value="US Route 101"/>
<Attribute name="abbrev" value="US101"/>
<Attribute name="max_speed_limit" value="65 MPH"/>
</DataObject>
<DataObject id="Highway880" type="Highway">
<QueryName value="880"/>
<QueryName value="I-880"/>
<QueryName value="Interstate 880"/>
<Attribute name="fullname" value="Interstate 880"/>
<Attribute name="abbrev" value="I-880"/>
<Attribute name="max_speed_limit" value="65 MPH"/>
</DataObject>
<!--Other data objects for other highways could be added here.-->
</Results>
The sample code includes only one ResultSpec element with a Query and Response child elements that use variables. The values for the variables are defined in two data objects. Users would see the following subscribed link result for the search query, "speed limit on 101":
When users search on the speed limit of 880, they would see a different result, even though we just created one result specification.
Matching Regular Expressions in the Query
If you used regular expressions in your query, you can display the user-entered query values in the custom result. The values of the attribute variables are simply the match groups of the regular expression. The attribute variable must have the following naming structure: the object identifier, followed by gr, and then the order of the attribute variable, starting from 0. Like all attribute variables, attribute variables that match regular expressions must be enclosed in brackets ([ ]). So the first attribute variable of the first regular expression match group would be [0.gr0]; the second, [0.gr1]; the third, [0.gr2]; and so on.
The following sample code demonstrates how you can create a response that includes the regular expression in the query.
<Results>
<ResultSpec id="Regex">
<Query>[RE:(\\d{1,3})\\.(\\d{1,3})\\.(\\d{1,3})\\.(\\d{1,3})]subnet</Query>
<Response>
<Output name="title">Subnet breakdown for [0.gr0].[0.gr1].[0.gr2].[0.gr3]</Output>
<Output name="more_url">www.foo.com</Output>
<Output name="text1">Class A subnet: [0.gr0]</Output>
<Output name="text2">Class C subnet: [0.gr2]</Output>
</Response>
</ResultSpec>
</Results>
The code matches queries like "127.0.0.1 subnet", and returns results that look like:
If your query has a regular expression that matches optional words, the corresponding attribute variables should still include the regular expression match in the numbering of the object identifiers. For example, a query such as <Query>[City] [RE:(to)?] [City]</Query> will trigger a custom result when a user types either "San Francisco Chicago" or "San Francisco to Chicago". Attribute variables that refer to the first data object, [City], would have 0 as its object identifier; attribute variables that refer to the optional match, [RE:(to)?], would have 1 as the object identifier; attribute variables that refer to the third data object, also [City], would have 2 as its object identifier. It does not matter whether the regular expression match is empty (as in search queries like "San Francisco Chicago") or not (as in search queries like "San Francisco to Chicago"), it should be accounted for.
Echoing the User's Query in Your Response
You can echo the literal text of your user's search term in your response. This is useful in instances where you want to incorporate the literal search query as a parameter of a search URL or quote the search query.
To echo your user's search queries, simply embed [q] in the response output. For example:
<Response>
<Output name="title">Speed limit info for [q]</Output>
<Output name="more_url">www.google.com/example/describe?hwy=[0.fullname]</Output>
<Output name="text1">The maximum speed limit on [0.fullname]</Output>
<Output name="text2">is [0.max_speed_limit].</Output></Response>
Displaying URLs in Your Responses
Some reserved characters—such as spaces, ampersands (&), and percent signs (%)—cannot be used in a URL, unless you use their escape characters. For example, the escape character for space is %20. So a web address like www.google.com/search addon.html should be written out as www.google.com/search%20addon.html.
The Subscribed Links API automatically escapes URL that includes attributes variables if it is inside any Output tag with a url value, such as <Output name="more_url">, <Output name="url1">, and <Output name="url2b">. If you want to override the escaping, append :noescape to the end of the attribute variable (for example: [0.fullname:escape]). The API will not escape a URL with just literal strings and no attribute variable.
If you want to escape the URL in other Output elements, append :escape to the end of the attribute variable (for example: [0.fullname:escape]).
In the following example, the URL in <Output name="more_url">www.myspeedlimitssite.com/describe?hwy=[0.fullname]</Output> and <Output name="text3">Escaped URL parameter for this highway: [0.fullname:escape]</Output> are escaped. In the first case, it is escaped because the API automatically escapes URL with attribute variables within <Output name="more_url"> </Output> tags; in the second case, because :escape is appended to the end of attribute variable.
<Results>
<AuthorInfo description="Find highway speed limits" author="Joe Author"/>
<ResultSpec id="HighwayMatch1">
<Query>speed limit on [Highway]</Query>
<Response>
<Output name="title">Speed limit info for [0.fullname]</Output>
<Output name="more_url">www.google.com/example/describe?hwy=[0.fullname]</Output>
<Output name="text1">The maximum speed limit on [0.fullname]</Output>
<Output name="text2">is [0.max_speed_limit].</Output>
<Output name="text3">Escaped URL parameter for this highway: [0.fullname:escape]</Output>
</Response>
</ResultSpec>
<DataObject id="Highway101" type="Highway">
<QueryName value="101"/>
<QueryName value="US 101"/>
<Attribute name="fullname" value="US Route 101"/>
<Attribute name="max_speed_limit" value="65 MPH"/>
</DataObject>
</Results>
The more_url and text3 output lines would have their attribute variables escaped to "US+Route+101", but the text1 output line will be left unchanged as "US Route 101".
Taking the Next Step
In the previous and current pages, we went through a few techniques for creating sophisticated queries and responses using variables and regular expressions. The next page, Managing Multiple Data Objects, tells you a few tricks to simplify your development process. You can encode your data objects into TSV files and do away with some XML tagging, and you can save time by borrowing data objects already created by other developers.
