JavaScript: Make Yahoo! Web Service REST Calls with JavaScript and XMLHttpRequest

AJAX web applications are all the rage these days, and one important aspect of AJAX (the "A" and, depending who you ask, the "X") is a mechanism of making asynchronous connections from the back end of a web application with an object called XMLHttpRequest (XMLHTTP for Internet Explorer). This request is used to retrieve XML or other data from web services such as those provided by us here at Yahoo!. In this HOWTO you'll learn how to make web service requests to Yahoo! Web Services with JavaScript and the XMLHttpRequest object. This page contains these sections:

This HOWTO uses the code contained in Yahoo! Search Web Services REST request, a sample created for the Yahoo! Developer Network JavaScript Developer Center.

How it All Works

In a traditional, non-AJAX web world, if your web application needs to get new data to update itself -- even if that's just a tiny bit of data -- you write your page so that when new data is required a user action (a button click, for example) triggers the browser to make an HTTP connection (a form submission) back to the web server. The problem is that with each HTTP connection, a new page is reloaded. All the elements of the page are broken down and recreated each time while the user waits for the network and waits for the page to redraw. Its incredibly inefficient, slow, and not much fun for the user.

With AJAX, you use all the same elements for building a web application -- HTML, CSS, JavaScript, and so on. But when you need new data for your application, you can make a network request for that data in the background using an XMLHttpRequest call. This network connection occurs independently of the HTTP browser request, and asynchronously, so the user can continue to interact with your application while the request is being made. Once you get a response back, you can use JavaScript and DHTML to redraw the existing page for the user -- no reload of the page. With a well-designed AJAX application there may be no need to reload or redraw the page until an entirely new aspect of the application is required (from a login mode to a shopping mode to a checkout mode, for example). With small enough pieces of data and a fast enough network connection the responsiveness of an AJAX web application can approximate that of a native client application.

Web services such as those provided by Yahoo! are perfect for AJAX as they provide sophisticated data in XML and easy-to-use JSON formats that are easily parseable and useable from within JavaScript at the back end of your Web apps. With Yahoo! Web Services data and XMlHttpRequest you can build complex, dynamic web applications.

There's one catch. Browser security restrictions prevent your web application from opening network connections to domains other than the one your application came from (cross-domain networking). If your web application loads data from the Yahoo! Web Services, this is a violation of browser cross-domain security policy. There are a number of mechanisms for working around this issue, but one of the easiest is to install a web proxy on your server that will pass requests from your application to Yahoo! web services and the data back again. See HOWTO: Use a Web Proxy for Cross-Domain XMLHttpRequest Calls for more information about the cross-domain networking issue and how to work with a web proxy.

In addition to the Web proxy, you'll need four other things to use XMLHttpRequest and the Yahoo! Web Services in your web application:

Each of these things is described in the remainder of this HOWTO.

Formulate the Yahoo! Web Services Request

To get Yahoo! Web Services data for your web application, you'll need the URL for a Yahoo! Web Services request. Most of the Yahoo! Web services are REST-based and return either XML or JSON (JavaScript Object Notation) data. For information about the various Yahoo! Web Services, see the documentation at the Yahoo! Developer Network. A summary of the Yahoo! products that include REST requests is also available at our JavaScript Developer Center. The documentation on Constructing REST Requests can help you put together the parameters for a Yahoo! Web Services request if you are unfamiliar with REST syntax.

Note: Some of the Yahoo! Web Services require an application ID, an identifier that can be used to identify your application. You can use the app ID to get usage information about your application from Yahoo!. You can use YahooDemo as the App ID to experiment with our services.

For example, here's a request from Yahoo! Search web search service for the keyword "persimmon" that returns ten results: WebSearchService /V1/webSearch?appid=YahooDemo &query=persimmon&results=2

By default the Yahoo! Web Services return XML output. With the output=json parameter, you can get JSON output instead: WebSearchService /V1/webSearch?appid=YahooDemo &query=persimmon&results=2 &output=json

For more information about JSON, see our JSON Documentation.

Note that if you are using a proxy to relay requests from your web application to the Yahoo! Web Services, the actual request URL you use from your web application is different from this URL, as you must relay your request through your web server proxy. For example, if you are using the PHP Proxy, the actual request looks something like this: php_proxy_simple.php?WebSearchService/V1/ webSearch?appid=YahooDemo&query=persimmon&results=2

This request will be made to -- the same domain your application came from, to avoid cross-domain browser issues -- and the domain of the Yahoo! Search web service is hard coded onto the proxy. The web service request (everything in the URL after the question mark) is related by the proxy onto the Yahoo! Search web site.

Create the XMLHttpRequest Object & Make the Request

The XMLHttpRequest object, as noted in the introduction, behaves the same across browsers, but you create it differently depending on whether your web application is running in Internet Explorer or a browser that supports the native XMLHttpRequest object (pretty much all other modern browsers). In Internet Explorer XMLHttpRequest is an ActiveX object called XMLHTTP. You can determine the appropriate object to create with a few tests:

var xmlhttp = null;
if (window.XMLHttpRequest) {
  xmlhttp = new XMLHttpRequest();
  if ( typeof xmlhttp.overrideMimeType != 'undefined') {
} else if (window.ActiveXObject) {
  xmlhttp = new ActiveXObject("Microsoft.XMLHTTP");
} else {
  alert('Perhaps your browser does not support xmlhttprequests?');

This code creates the XMLHttpRequest object and stores it in the xmlhttp variable. Once you have an XMLHttpRequest object -- be it the Mozilla or IE flavor -- making the request is easy:'GET', url, true);

The open method takes three arguments:

  • The HTTP method to use for the request (GET, POST, HEAD, etc).
  • The URL to request (here, the value of the url variable). The URL can be relative to the current page.
  • Whether the connection should be asynchronous (true for yes). With a synchronous connection your script will wait for the connection to complete for continuing with processing. The A in AJAX stands for Asynchronous, so unless you have a reason for using synchronous connections, use true here.

The send method, in turn, takes one argument: the content to send. Here since we're using a GET method the content is null, but if you were using a POST the content to post to the server would be indicated here.

The open method will fail if the domain name of the URL is different from that of your web application. Remember, browsers require network connections to be made to the same domain as the page itself. That is why the proxy needs to be used.

Create a Callback

The core notion of of using XMLHttpRequest object in an AJAX applications is that the request is asynchronous. The asynchronous connection means your code (and your user) isn't waiting around for the request to come back before anything else can happen on the page. Life goes on while your network requests are being made and responses are processed in the background. The difficulty with asynchronous connections is that rather than just a few simple lines of linear networking code -- open the connection, make the request, read the response, do something with it -- you need to create an independent callback function that is executed each time the state of the XMLHttpRequest object changes, and then processes your result when the request is done. The good news is that XMLHttpRequest has several properties to make this easy, and the callback check is essentially boilerplate code that you can put after your xmlhttp.send call:

xmlhttp.onreadystatechange = function() {
  if (xmlhttp.readyState == 4 && xmlhttp.status == 200) {
    // do something with the results
  } else {
    // wait for the call to complete

The important properties here are:

  • readyState, an integer that indicates the current state of the object.
  • onreadystatechange, an event handler that you can define to fire when the state of the object changes.
  • status, containing the HTTP response code once the readyState is complete.

Although the readyState property of the XMLHttpRequest object can have five possible integer values (uninitialized, loading, loaded, interactive, complete), generally the only state you're interested in is 4, complete, which means that the request has completed. This example also checks the status property to make sure that the request was successful (the xmlhttp.status property was 200). If the readyState was 4 and the status was some other value you might want to do something different with that response. A 503 response, for example, is an Service Unavailable error for the Yahoo! Search Web Services, which means that you won't have any data available for your application to use. You'll need to find a way to gracefully handle that exception if it arises. (Note, however, that other Yahoo! APIs may have other methods of returning errors, so you can't necessarily rely on HTTP error codes).

Parse the Result

After the XMLHttpRequest call is complete (the readyState is 4), the response data is contained either in the responseText property, the responseXML property, or both. If the data you get back from the web service is in XML format, both responseXML and responseText are filled. If the data is in any other format, responseText is filled. However, whether responseXML gets filled is dependent on the browser and the Content-type the server returns (text/xml or application/xml). In practice, responseText seems to be more reliably filled across browsers and web services.

If the responseXML property is filled by the XMLHttpRequest object, that property contains a Document object whose elements you can access in JavaScript using standard DOM methods (getElementsByTagName, etc).

If your response format was XML but all you have is responseText, you will need to use an XML parser to get the information you need out of the XML text. Both Mozilla and Internet Explorer have XML parsers built in; see this tutorial from for help in getting started. In addition the open-source XML for <SCRIPT> (xmljs) is a fully featured XML parser which includes many other tools for XML development within JavaScript.

If your response was in JSON format parsing is perhaps easiest of all. JSON is short for JavaScript Object Notation -- JSON is JavaScript. To interpret a JSON response just eval the response, and you'll get a JavaScript object back:

var myObj = eval ( xmlhttp.responseText );

Once you have the data in hand you can update the page with standard JavaScript and DHTML methods. No need to reload or redraw the entire page -- just modify the part of the page that needs the new data.

For More Information

For more information on JavaScript, XMLHttpRequest, Yahoo! Web Services APIs and other JavaScript development topics, see The Yahoo! Developer Network JavaScript Developer Center.

The code for this example is available at Yahoo! Search Web Services REST request.