XML Reference Guide

For a few years now, Google's been the only game in town for developers looking to easily access a major search engine's data in their applications.

Not anymore.

Yahoo!, possibly as part of a bid to win the hearts and minds of developers and other early adopter types, has released Yahoo! Web Services v1.0, which enables developers to make use of Yahoo! search results in their own applications.

Yahoo! Web Services has one major difference from Google Web Services: it uses REST, rather than SOAP.

That means that getting the result of a search is a sample matter of constructing an appropriate URL and calling it. Rather than building a special client application, as you must do for a SOAP request, you can simply call a REST URL from the browser, if all you're intersted in is seeing the results.

For example, I can do a web search term "firefly" by calling the following URL:

http://api.search.yahoo.com/WebSearchService/V1/webSearch?appid=InformITXML&query=firefly&format=html

Don't worry about the actual URL -- we'll get to that in a moment.

When I enter that URL in my browser, I get a response something like this. (Click to see the full-size image.)

Of course, it's not much use that way; if I wanted to see the results myself, I'd be much better off simply using the Yahoo! web site. No, this data is meant to be used by an application. For example, I might want to display the top 5 results for "firefly" on one of my web pages. I could do that by constructing a routine that makes an HTTP connection and analyzes the resulting document. (In fact, I'll do that in the next section.)

Before we talk about how to build a search, let's talk about what you can search. Yahoo! has made available the following search services:

• Web Search: The classic web search, this service enables you to look for web pages that satisfy the requested query.
• Image Search: Searches for images on the world wide web. Results include the URL for the actual image, a thumbnail version of the image (if there is one) and the page on which the image appears.
• Video Search: Similar to the Image Search, this search enables you to search for video files on a particular topic. Results include the URL for the actual file as well as summary text (if available) and information on the file itself, such as how many audio channels it has and whether it's streaming or not.
• Local Search: Enables users to search for businesses that satisfy a particular query -- and that are within the specified radius of a target location. Results include business information and a map URL.
• News Search: Searches for news items that satisfy the specified query. Results include the URL for the actual item, as well as information on the source and date of the item.

Yahoo! also offers two sub-services: Spelling, which gives you the correct spelling for a term -- or at least a suggestion for the correct spelling -- and Related, which returns a list of queries that are thought to be related to the requested query.

Constructing a request for Yahoo! Web Services is the same as constructing any other REST request. For example, let's look at that "firefly" request we were talking about earlier. First, we need the base Web Search URL:

http://api.search.yahoo.com/WebSearchService/V1/webSearch

Next we need to add the parameters. Each parameter comes as a name-value pair. In our case, those name-value pairs are:

appid=InformITXML
query=firefly
format=html

The appid is a an ID unique to your application; you register it with Yahoo! and it identifies requests made through your appliocation. The query is the search term you're looking for. The format is the type of results you're looking for. For example, you could search for just PDF files. (The default is to return all results.)

To put these parameters together, add a question-mark to the end of the base URL and join the name-value pairs with asterisks, as in:

http://api.search.yahoo.com/WebSearchService/V1/webSearch?appid=InformITXML&query=firefly&format=html

The result is a ResultSet of Result elements. The contents of the Result elements depends on the type of search.

Next: using the Yahoo! Web Services 1.0 API.