ave you ever wanted to implement search capabilities on your own Web site but didn’t want to implement the logic and deal with issues such as storage and indexing? Now you can. The Live Search web service allows your site to make up to 25,000 queries a day for use in both commercial and non-commercial sites?at no cost.

Figure 1 shows the Live Search home page. In addition to a standard search service, Live Search offers specialty searches in categories such as images, news, maps, and more.

	?
Figure 1. The Live Search Home Page: You can access both regular and specialty searches through the Live Search home page.

Two Access Methods

Live Search offers two ways for site developers to build search capabilities into their sites. The Live Search Box allows a user to harness the power of Live Search without writing any code. It provides a fast, customizable search for any Web site. You can find details on how to get started with this option here. Basically, you just follow the wizard and copy the HTML code provided into your site.

Developers seeking more advanced search capabilities should use the Live Search Web Service, which lets you query the Live Search Engine directly. The Live Search Web Service is an Extensible Markup Language (XML) service with a Simple Object Access Protocol (SOAP) API that allows users to create a custom search engine that can query for Web results, images, news, phonebook listings, feeds, and meta tags.

	?
Figure 2. The Developer Center Home Page: Here, you can download the Search SDK and create and manage Application IDs.

You should use this service when you want programmatic control over search terms and result displays.

You can find the fully documented SDK online. The documentation describes the requirements, the class libraries for the Live Search Web Service, and the terms of use. It also contains sample code demonstrating use of the Live Search Web Service.

Before You Start
To use the API, you need an Application ID. You can register and manage your Live Search Application IDs at the Live Search Developer Center. Figure 2 shows the Developer Center home page.

When creating a new Application ID, give your application a name and make note of the assigned Application ID as you will need to use it in your source code. Figure 3 shows the “Get Application ID” page.

? Figure 3. Getting an Application ID: Here’s the Developer Center page where you get an Application ID.

? Figure 4. The Add Web Reference Dialog Box: In Visual Studio, add a reference to the Live Search Web Service through the Add Web Reference dialog.

Referencing the Web Service
After obtaining an Application ID, you need to configure your application to consume the Live Search Web Service. In Visual Studio, add a Web Reference to the WSDL located at http://soap.search.msn.com/webservices.asmx?wsdl. Figure 4 shows the Add Web Reference dialog box with the Live Search Web Service. After the application has located the Web Service, enter a name for the service and click the Add Reference button. All code examples in this article use “LiveSearch” as the service name.

Creating a Basic Search
With the Live Search Web Service reference in place, you now have access to the Search method. The following code snippet demonstrates performing a basic search:

   MSNSearchService serv = new MSNSearchService();   SearchRequest sRequest = new SearchRequest();   SourceRequest[] sr = new SourceRequest[1];   sr[0] = new LiveSearch.SourceRequest();   sr[0].Source = LiveSearch.SourceType.Web;   sr[0].ResultFields = ResultFieldMask.All;   sRequest.Query = "Live Search Articles";   sRequest.Flags = SearchFlags.None;   sRequest.Requests = sr;      // Replace with your own Application ID   sRequest.AppID = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXX";   sRequest.CultureInfo = "en-US";   SearchResponse resp = serv.Search(sRequest);

	?
Figure 5. Basic Search Query Results: Using the Live Search Web Service to search the web for “Live Search Articles” gives these results.

This basic search searches the entire Internet for results that contain “Live Search Articles” and returns all the result fields. The preceding query returns the results shown in Figure 5.

The web service returns search results in a SourceResponse object, which contains an array of results. Depending on the type of search and the fields requested, the results may contain a variety of fields. You should check each field for null before using to avoid unwanted exceptions:

   SearchResponse resp = serv.Search(sRequest);   foreach (Result r in resp.Responses[0].Results)   {   string title, description, url;     title = (!String.IsNullOrEmpty(r.Title))        ? r.Title : "";     description =        (!String.IsNullOrEmpty(r.Description))        ? r.Description : "";     url = (!String.IsNullOrEmpty(r.Url))        ? r.Url : "";   }

	?
Figure 6. Using the ResultFieldMask: Search query results using ResultFieldMask to display title, description, and displayurl fields.

The API allows customization of the fields returned using the ResultFieldMask. For example, if you wanted to display only the title, description, and displayurl fields, you would use the following code:

   SourceRequest[] sr = new SourceRequest[1];   sr[0].ResultFields =        ResultFieldMask.Description |        ResultFieldMask.DisplayUrl |        ResultFieldMask.Title;

You can see the change in the search results in Figure 6.

Limiting Search Sites
So far, all the examples search the entire Internet for results; however you can use the API to allow users to limit the search to specified sites. The following code searches for items about “Virtual Earth” on the http://www.soulsolutions.com.au site only:

   SearchRequest sRequest = new SearchRequest();   sRequest.Query =      "Virtual Earth site:www.soulsolutions.com.au";

Figure 7 shows the results.

	?
Figure 7. Site-Constrained Search: Limiting the search to a specific site provides these results.

Customizing Your Search
There are a number of ways to customize the search and results returned, including:

• Flags
• Safe search
• Searching for images
• Spelling suggestions
• Implementing paged or limited result sets

Flags
Setting flags on the search object allows further customization to a search query. Table 1 describes the full list of available flags.

	?
Figure 8. Using MarkQueryWords: The figure shows the search query results with query parameters marked in bold text.

As an example, here’s a more detailed look at the MarkQueryWords flag. You use MarkQueryWords when you want to highlight query terms returned in the result set. The following code snippet shows how you use this to mark query terms in bold:

   SearchRequest sRequest = new SearchRequest();   sRequest.Flags = SearchFlags.MarkQueryWords;

Figure 8 shows the change in the result set.

Safesearch
For users who are concerned with the content that may be returned in results, the API allows users to filter out sexually explicit images and text from search results using the SafeSearchOptions object.

Use SafeSearchOptions.Moderate to filter out explicit images or SafeSearchOptions.Strict to filter both explicit images and text:

   SearchRequest sRequest = new SearchRequest();   sRequest.SafeSearch =      SafeSearchOptions.Moderate;

	?
Figure 9. Image Search: Here’s an example response from an Image search.

Searching for Images
You can also use the API to search only for images. Using the SourceType.Image in the Source Request returns full-size and thumbnail image information such as size, height, width, and URI. The following code snippet shows how to use the search source and result fields to return images:

   SourceRequest[] sr = new SourceRequest[1];   sr[0].Source = LiveSearch.SourceType.Image;   sr[0].ResultFields =        ResultFieldMask.Description |        ResultFieldMask.Image |        ResultFieldMask.Title;

You can see the results of the search in Figure 9. Table 2 shows the full list of valid SourceTypes.

Spelling Suggestions

Users often misspell words in their search criteria, so spell-checking a user’s search criteria before performing a search is a great way to improve the usability of your system. The following code snippet shows how you can use the Spelling SourceType to determine if the search criteria are spelled correctly:

   SearchRequest sRequest = new SearchRequest();   SourceRequest[] sr = new SourceRequest[1];   sr[0].Source = LiveSearch.SourceType.Spelling;   sr[0].ResultFields = ResultFieldMask.All;   sRequest.Query = "vertual earth";

Implementing Paged or Limited Result Sets
Other great ways to improve usability of your search solution are limiting the total number of records returned or showing the results in a paged fashion. You can get the total number of results as shown below:

   SearchResponse resp = serv.Search(sRequest);   int total = resp.Responses[0].Total;

To control the number of results returned by a search, set the Count property:

   SourceRequest[] sr = new SourceRequest[1];   sr[0].Count = 10;

When implementing a data paging solution, you need to know what page (or what record number for the first record of the page) you wish to display and the total number of records in a page. The API supports an Offset property that represents the record number from which to start retrieving results. The following code snippet retrieves five results starting at record number five:

   SourceRequest[] sr = new SourceRequest[1];   sr[0].Count = 5;   sr[0].Offset = 5;

This article demonstrated only the basics of a search solution, the possibilities are endless. Here are some useful links to help you get started and find more information:

• The Live Search Interactive SDK
• The Live Search API on MSDN
• The Live Search Developer Center
• The Live Search Development MSDN Forum
• Windows Live Community Site