Make Yahoo! Web Service REST Calls

There are several ways to make Yahoo! Web Services REST requests using Java. In this HOWTO, we discuss and demonstrate some methods using the Yahoo! Search Web Service.

HTTP GET Requests

An HTTP GET request is all you need to retrieve basic search results from the Yahoo! Search Web Service. GET requests are easy to debug because you can paste it in your web browser and quickly see if the query has been constructed properly. Some web services require requests via POST for tasks such as image uploading or the modification of HTTP headers to set cookies. We will cover both GET and POST requests in the following examples.

The first example is a request for the keyword "umbrella" that returns 10 results:

String request = "";

We make a simple HTTP GET request to retrieve the results:

HttpClient client = new HttpClient();
GetMethod method = new GetMethod(request);

// Send GET request
int statusCode = client.executeMethod(method);

Next, we process the response from Yahoo! Web Services and print the XML response to the console:

        InputStream rstream = null;
rstream = method.getResponseBodyAsStream();
BufferedReader br = new BufferedReader(new InputStreamReader(rstream));
String line;
while ((line = br.readLine()) != null) {

A complete code example is available in the file

HTTP POST Requests

POST requests are used by web browsers when submitting data from HTML forms. The content type "multipart/form-data" should be used for submitting forms that contain files, non-ASCII data, and binary data.

For POST requests, we construct the POST data separately from the request URL and parameters.

String request = "";
    HttpClient client = new HttpClient();
PostMethod method = new PostMethod(request);
// Add POST parameters

// Send POST request
int statusCode = client.executeMethod(method);
InputStream rstream = null;

// Get the response body
rstream = method.getResponseBodyAsStream();

The response is the same as the first example and can be processed in the same way.

A complete code example is available in the file

POST Requests with Sockets

Here's a POST example where we use sockets instead of the URL and URLConnection objects.

// Create POST data string
String postdata = "appid" + "=" + URLEncoder.encode("YahooDemo", "UTF-8");
postdata += "&" + "query" + "=" + URLEncoder.encode("umbrella", "UTF-8");
postdata += "&" + "results" + "=" + URLEncoder.encode("10", "UTF-8"); // Create a socket to the host
String hostname = "";
int port = 80;
InetAddress addr = InetAddress.getByName(hostname);
Socket socket = new Socket(addr, port); // Send header
String path = "/WebSearchService/V1/webSearch";
BufferedWriter bw = new BufferedWriter(new OutputStreamWriter(socket.getOutputStream(), "UTF8"));
bw.write("POST " + path + " HTTP/1.0\r\n");
bw.write("Content-Length: " + postdata.length() + "\r\n");
bw.write("Content-Type: application/x-www-form-urlencoded\r\n");
bw.write("\r\n"); // Send POST data string

A complete code example is available in the file

Error Handling

Yahoo! offers many REST web services but they don't all use the same error handling. That's because some of Yahoo!'s Web Services came from companies that Yahoo! acquired, such as Flickr and Upcoming. These companies already had their own web services error handling in place. However, most web services that we developed in-house, including all of our Yahoo! Search Web Services, use the documented error handling.

If there is a problem serving your request, you'll receive a response with an HTTP error code and possibly an XML error response. The HTTP status code is the best way to detect errors since some failures won't return any XML. A typical XML error response might look like this:

<?xml version="1.0" encoding="UTF-8"?>
<Error xmlns="urn:yahoo:api">
The following errors were detected:
<Message>invalid value: query (empty or missing)</Message>

Get the HTTP status code and then output the appropriate message:

int statusCode = client.executeMethod(method);

switch (statusCode) {
case 400: {
System.out.println("Bad request. The parameters passed to the service did not match as expected. The Message should tell you what was missing or incorrect.");
System.out.println("Change the parameter appcd to appid and this error message will go away.");
case 403: {
System.out.println("Forbidden. You do not have permission to access this resource, or are over your rate limit.");
case 503: {
System.out.println("Service unavailable. An internal problem prevented us from returning data to you.");
default: System.out.println("Your call to Yahoo! Web Services returned an unexpected HTTP status of: " + statusCode);

The source code for this example can be found in the file

For More Information

For more information on using Java with Yahoo! Web Services APIs, see The Yahoo! Developer Network Java Developer Center.

Yahoo Forum Discussions