Contents


Introduction

Thank you for partnering with LocalXML. Now that you have become a member of our ad network, you will be able to show Overture paid search results on your site and format them in your own style. To make this easier, we have provided our search results in a standard format - XML (eXtensible Markup Language). XML is a platform-independent way of defining and transmitting data. With it, all of our partners have the flexibility to manage the display (formatting, layout, design, look and feel) of Overture results. The XML specification is available at W3C.

LocalXML Technology Summary
The LocalXML algorithm first calls on Overture's ad inventory for city+category. If there is no ad inventory, it may check state+category depending on the category. If still no ad inventory, it will default to category. Even a straight category search will often turn up local-esk listings like "Find local doctors in your area." The percentage of searches resulting in local results will depend on your category-specific and city-specific traffic. Assuming your high traffic categories are more mainstream (attorneys, hotels, etc.) than the more obscure ones (air duct cleaning) and assuming the directories supporting the larger cities get more traffic than smaller ones, you should get a large portion of local results on a per-search basis. The above description is just our LocalXML technology. Further localization will occur via Overture's LocalMatch product, of which you will also benefit from. It is also important to note that the algorithm-supplied keyword for each category may change over time. For instance, if "aircraft charter" returns higher priced bidders than "airplane charter", our system updates the tables with the more profitable (but still category matched) keyword combo. All of this happens behind-the-scenes on our end so you guys can sleep at night while we do all the work.

Regarding per-click revenue, it is important to move "with" the market and not ahead of it. Although the recent sharp increase in local advertisers jumping onto paid search is driving up local-related keywords, most categories will still yield far higher PPCs (revenue per click) with a straight category-based keyword query. As the local-based ad inventory deepens (thus driving up PPCs), our system automatically shifts further over to local-based keyword combos.


XML URL Format
Each partner feed is accessed by a custom LocalXML interface. A typical URL will be of this format:

   http://localxml.com/feed.php?partner=<partnerID>&city=<cityID>&cat=<categoryID>

where <partnerID> will be replaced by the partner's ID as chosen by LocalXML, while both <cityID> and <categoryID> will be replaced by the relevant numeric codes supplied to you by LocalXML support. The cityID look-up table can be found here.

For partner sites that are dynamically generated using either a database or flat files, the LocalXML numeric mapping will simply be two additional columns to pull from. If your site is static, please see below for ways to parse XML into a static HTML page.

Our preference is to receive Host: header information from your server on each request. Host: headers are an HTTP: protocol feature, optional in HTTP 1.0, and required in HTTP 1.1. Host: headers are another way we manage your service, and they can help troubleshoot problems.

Your XML results will include a URL giving the schema location. The schema is made available particularly for QA and development time data validation. In particular, it is recommended to carefully QA any new implementations, including use of new character encodings and new page layouts. In these cases, full validation of our XML is suggested. After launch, when your production systems query the XML Interface, it is not necessary to retrieve the schema with each new query. For performance reasons, we request that you limit your downloads of the schema file to the lowest level necessary.

The DNS settings (TTL), which are in effect on Overture DNS servers, are optimized for serving as well as problem resolution. We request that you follow them as much as possible, and in any event do not cache the Overture server's IP address longer than 10 minutes, as this can result in delays to failover operations and disruption of service to your users.

Optional Parameters
Below is a list of parameters and possible arguments that can be supplied to the XML interface. Please note, these optional parameters are case sensitive.

maxCount - This parameter specifies the maximum number of search results to return. Possible arguments to this parameter are of this form: maxCount=n, where n is an integer greater than zero.

adultFilter - This parameter specifies whether or not to filter the search results to remove adult listings. Possible arguments to this parameter are of this form: adultFilter=clean for filtered results (search results will not contain adult content) or adultFilter=any for non-filtered results.

start - This parameter provides a short-cut for navigating through a large number of results in a Result Set. &start=11&maxCount=5 is used to request a set of five results beginning with the result at rank 11. Results numbered 1 to 10 in this example would not be included in the returned XML. Possible values for this attribute are any positive integer. Using this parameter with a value other than a positive integer produces the default result of &start=1.

Usage Examples of Optional Parameters
Example 1:
A user on a Phoenix-based web site owned by Mycoolcompany searches for 'attorneys' in the site's directory. Mycoolcompany is family oriented and does not want to display adult search results. LocalXML has created a "Partner" tag for them (1). The URL mycoolcompany should access for Overture listings looks like this:

  http://localxml.com/feed.php?partner=1&city=0455000&cat=1135&adultFilter=clean

Example 2:
A user on a Phoenix-based web site owned by Mycoolcompany searches for 'attorneys' in the site's directory. Mycoolcompany wants to limit the number of paid listings to three. LocalXML has created a "Partner" tag for them (1). The URL mycoolcompany should access for Overture listings looks like this:

  http://localxml.com/feed.php?partner=1&city=0455000&cat=1135&maxCount=3

Code for Processing (Parsing) XML
Sample XML Parser Codes:

Using JavaScript
We have developed JavaScript code that will parse the XML for you. Below you will find the source code for two types of our JavaScript (View Source to cut-and-paste). Please note that JavaScript takes a little longer to load and the listing output will not show up as html content when you view source or when search engine bots spider your site.

  • JavaScript example using our default stylesheets
  • JavaScript example with CSS, allowing you to determine font, color, size, etc.


    Using iFrames
    Another solution for static html pages is to insert iframes that display the results derived from a script that parses the XML. The code on the static html page would look something like this:

    <iframe src="http://link_to_your_parsing_script" height="xxx" width="yyy" scrolling="auto" border="0" frameborder="0"></iframe>

    Using XSL/t

    The following code samples are written for Linux and may vary from system to system. They also use flat files in some cases to read and write data. Modifications will be necessary to read and write data through sockets.

    XSL/t using Java
    This is an example of how to translate an XML file to HTML with an XSL/t using the James Clark XT package for Java. This package can be downloaded from http://www.blnz.com/xt/. The Xerces package will also be necessary for this sample and is available from http://xml.apache.org/xerces-j/index.html.

    XSL/t using Xalan
    This is an example of how to translate an XML file to HTML with an XSL/t using the Xalan package provided by Apache. This package can be downloaded from http://xml.apache.org/xalan-j/index.html. The Xerces package will also be necessary and is available from http://xml.apache.org/xerces-j/index.html.

    XSL/t using Sablotron
    This is a perl example that parses an XML file and translates it to HTML using an XSL/t, with the XML::Sablotron module. The package used in this example can be downloaded from http://www.gingerall.com/. Sablotron for perl requires the Expat parser be installed (also available at Gingerall).

    Note: HTML rendering of search results can be accomplished by an XSL/t. Here is a sample HTML rendering of a paid Listing:



    1. 20% off @ PETsMART.com's Travel Corner
    Gear up for Summer Travel with your pet. Our Travel Corner has unique items to make trips comfy and easy for you and your pet. And at 20% off you'll have enough left over to buy souvenirs!
    www.petsmart.com
    • Support Contact
    If you need additional implementation support after reviewing this documentation and the following reference links, please email your questions to support@litmusmedia.com.
    Additional Reference Links


    Copyright © 2005 - All Rights Reserved.
    Litmus Media, Inc.