This weekend I wanted to play a bit with Yahoo's Search API, so I thought I'd share my results here. Yahoo has a pretty big developer network, but unfortunately they have no ColdFusion examples. (Hey, Yahoo, lets fix that!)

I had a bit of trouble finding the actual API however. After a few minutes of searching I found it here: Web Search Documentation. Yahoo uses a simple REST based process. This means you can use CFHTTP and URL parameters instead of a full fledged web service. The result is a nice XML packet you can easily parse.

The next thing you need to test Yahoo's API is an application ID. You can get one using this form: http://api.search.yahoo.com/webservices/register_application.

One last note. Yahoo's FAQ says:

Q: Why does ColdFusion keep giving me a "Connection Failure" message?
It's an encoding issue. You need to add to your cfhttp call and it should work.

This did not work for me. Instead I used the charset attribute of the cfhttp itself. Here is a simple example. I changed the appid value though:

<style> li { margin-bottom: 10px; } </style>

<cfset searchTerm = "coldfusion"> <cfset results = "10"> <cfset appid = "billgatesisdabomb">

<cfhttp url="http://api.search.yahoo.com/WebSearchService/V1/webSearch?appid=#appid#&query=#urlEncodedFormat(searchTerm)#&results=#results#" result="result" charset="utf-8"> </cfhttp>

<cfif len(result.fileContent) and isXml(result.fileContent)>

<cfset xmlResult = xmlParse(result.fileContent)>

<cfoutput> Your search for #searchTerm# resulted in #xmlResult.resultSet.xmlAttributes.totalResultsAvailable# matches. You returned #xmlResult.resultSet.xmlAttributes.totalResultsReturned# results.

<ul> </cfoutput>

<cfloop index="x" from="1" to="#xmlResult.resultSet.xmlAttributes.totalResultsReturned#"> <cfset node = xmlResult.resultSet.xmlChildren[x]> <cfset title = node.title.xmlText> <cfset summary = node.summary.xmlText> <cfset iUrl = node.url.xmlText> <cfset clickurl = node.clickurl.xmlText>

<cfoutput> <li><a href="#clickurl#">#title#</a><br> #iURL#<br> #summary# </cfoutput> </cfloop>

<cfoutput> </ul> </cfoutput>

</cfif>

I'm not sure I even need to explain anything here. The CFHTTP call is pretty standard, again note the charset attribute. Also be sure to check the documentation for what all the URL parameters mean. The doc also explains the XML result. Honestly I just dumped it and figured it out. The only thing confusing was the "clickURL". Yahoo wants you to use that url for html links to help them track usage of the API.

Tomorrow I'll write up a somewhat more useful example of this API.