XML Reference Guide

Mashups, or applications that use data from a number of difference sources -- particularly web services sources -- are all the rage these days, so I thought I'd take a few moments to discuss a service that's not typically used: the eBay API.

eBay, as you probably know, is the world's largest auction site, offering, well, just about anything. (I still can't find a Sony IDC-SX35 Digital Voice Recorder, but maybe that's just me.) From the eBay browser-based interface, you can list items for sale, bid and buy them, and search for specific item, paying a fee to eBay when you sell an item.

eBay also makes it possible to show eBay information outside of the confines of the eBay site. For example, if you were creating a web page that includes information on, say, toy trains, you can add toy trains that are currently for sale. You could also create a page that shows your own auction listings and provides a link back to the eBay site so users can make a bid. In fact, eBay provides a fairly complete SOAP-based web service that enables you to build complete applications for buying and selling on the site.

In this case, however, we're going to start small, creating a simple web page that includes a few items provided by eBay's REST API, which simply enables you to execute a search. Using Java, we'll create the request, parse the XML, and pull out the appropriate information. We'll then use that information to create HTML, which we'll then output first to the command line and then to a web page.

The first step is to create your developer credentials. Execute the following steps:

1. Go to eBay's developer site and join the developer program.
2. When you fill out the form, eBay will send you a confirmation email that includes a confirmation code. Check your email and follow the instructions to use that code to generate your application keys.
3. In order to make requests, you will have to use an eBay account, but when you are creating your application you will actually be working against the "sandbox," a test version of the database. Create a sandbox test account for these requests. (Once your application is complete and you are making requests against the production database, you'll use your "real" eBay account.)
4. Create an eBay REST API token, which you'll include in your requests. Go to eBay's token tool. Choose "Sandbox" for the environment and enter the keys you received in step 2.

To make sure things are working, try a sample call, such as:

http://rest.api.sandbox.ebay.com/restapi?CallName=GetSearchResults&RequestToken=yourTokenHere&RequestUserId=yourUseridHere&Query=toy%20boat&Schema=1

You should see a result such as figure 1, with an Ack element of Success.

Figure 1: The sample request

Several parameters can come in handy in building your requests:

• Category: Optional, this defaults to 0, but can be used to limit your search to a particular numeric category code.
• IncludeSellers: You can use this parameter to limit your search to specific sellers. For example, you could display only your own items. This parameter can include up to 100 comma delimited seller ids.
• Query: The keywords for your search, with spaces represented by %20. This parameter is limited to 350 characters.
• EndTimeFrom and EndTimeTo: These parameters enable you to create a time range for items returned by the search.
• MaxResults: Unless you specify otherwise, the default search returns up to 100 items, but you can use this parameter to specify a set of up to 400 items.
• Skip: This parameter enables you to create a "pagination" effect, skipping the number of items you'd retrieved in previous calls.
• Schema: This parameter determines whether you will use the "legacy" API, which will stop functioning June 1, 2006, or the "new" XML API. Set this value to 1 for the new API.
• TotalOnly: Normally the request returns item information, but if you just want to know how many items would be returned by this search, set this parameter to 1.

You can get a full list of input parameters in the REST API documentation.

As with any REST application, you can most easily test the construction of your requests by entering them in your browser. You should get a response something like:

<?xml version="1.0" encoding="UTF-8"?>

<GetSearchResultsResponse xmlns="urn:ebay:apis:eBLBaseComponents">
  <Timestamp>2005-12-29T04:55:46.403Z</Timestamp>
  <Ack>Success</Ack>
  <Version>437</Version>

  <Build>e437_core_Bundled_2146580_R1</Build>
  <SearchResultItemArray>
    <SearchResultItem>
      <Item>
        <ItemID>4504295322</ItemID>

        <ListingDetails>
          <StartTime>2005-12-27T14:35:50.000Z</StartTime>
          <EndTime>2006-01-03T14:35:50.000Z</EndTime>
          <ViewItemURL>http://cgi.sandbox.ebay.com/ws/eBayISAPI.dll?ViewItem&amp;item=4504295322&amp;category=617&amp;ssPageName=WDVW&amp;rd=1</ViewItemURL>

        </ListingDetails>
        <SellingStatus>
          <BidCount>0</BidCount>
          <CurrentPrice currencyID="USD">15.5</CurrentPrice>
        </SellingStatus>

        <Site>US</Site>
        <Title>Claymation Christmas - Will Vinton New DVD! + Easter!</Title>
        <ListingType>Chinese</ListingType>
        <BuyItNowPrice currencyID="USD">15.95</BuyItNowPrice>

        <Currency>USD</Currency>
        <GiftIcon>0</GiftIcon>
        <SiteHostedPicture>
          <GalleryType>None</GalleryType>

        </SiteHostedPicture>
        <SubTitle></SubTitle>
        <PaymentMethods>PayPal</PaymentMethods>
        <Country>US</Country>

        <Storefront>
          <StoreCategoryID>0</StoreCategoryID>
          <StoreCategory2ID>0</StoreCategory2ID>
          <StoreURL>http://stores.sandbox.ebay.com/id=396492</StoreURL>

          <StoreName>Rover number Five</StoreName>
        </Storefront>
        <PostalCode>98604</PostalCode>
        <ShippingDetails>
          <ShippingType>NotSpecified</ShippingType>

        </ShippingDetails>
        <SearchDetails>
          <BuyItNowEnabled>true</BuyItNowEnabled>
        </SearchDetails>
      </Item>

      <SearchResultValues>Picture</SearchResultValues>
    </SearchResultItem>
    <SearchResultItem>...</SearchResultItem>
  </SearchResultItemArray>
  <ItemsPerPage>100</ItemsPerPage>

  <PageNumber>1</PageNumber>
  <HasMoreItems>false</HasMoreItems>
  <PaginationResult>
    <TotalNumberOfPages>1</TotalNumberOfPages>

    <TotalNumberOfEntries>6</TotalNumberOfEntries>
  </PaginationResult>
  <CategoryArray/>
</GetSearchResultsResponse>

Note the structure of the returned data. At the beginning is information about the search itself, such as the version of the API responding to the call and whether or not the request was successful. (In the case of an error, information as to the cause will be provided in the body of the response.) Next is the SearchResultItemArray, which contains an element for each result. Each resulting item consists of information about the item to be sold, as well as information about the auction itself, such as the number of bids and the current price.

Now let's go ahead and analyze the data using Java.

Start by creating the basic application:

import javax.xml.parsers.DocumentBuilder;
import javax.xml.parsers.DocumentBuilderFactory;
import org.w3c.dom.Document;
import org.w3c.dom.Element;
import org.w3c.dom.NodeList;
import org.w3c.dom.Node;

public class ShowFile {

   public static void main (String args[]) {

       String requestToken = your token here;
       String requestUserId = your sandbox user ID here;
       String query = args[0];

   }
}

First we're importing the classes we're going to use. The requestToken is the REST API token is the value you retrieved in step 4 above. (Note that it's the REST API token, and not the application token.) The requestUserId is the eBay user ID you created for the sandbox in step 3.

Now create and parse the request:

...
public class ShowFile {

   public static void main (String args[]) {

       String requestToken = your token here;
       String requestUserId = your sandbox user ID here;
       String query = args[0];


       String docString = "http://rest.api.sandbox.ebay.com/restapi?CallName=GetSearchResults"+
             "&RequestToken="+requestToken+
             "&RequestUserId="+requestUserId+
             "&Query="+query+
             "&Schema=1";

       Document doc = null;
       try {
           DocumentBuilderFactory dbf = 
                    DocumentBuilderFactory.newInstance();
           DocumentBuilder db = dbf.newDocumentBuilder();
           doc = db.parse(docString);
       } catch (java.io.IOException e) {
           System.out.println("Can't find the file");
       } catch (Exception e) {
           System.out.print("Problem parsing the file.");
       }

       Element root = doc.getDocumentElement();
       System.out.println("The root element is " + 
                                      root.getNodeName() + ".\n");

   }
}

The actual URL for the request is based on the appropriate host name -- we'll change it to rest.api.ebay.com for production -- and the fact that there's only one allowable REST call, GetSearchResults.

From there we have standard Document Object Model code. First, using the JDK implementation, we create a DocumentBuilder and use it to parse the data found at the URL in the request. Once we have the Document object, we can request the root element to make sure it's working. If you run the application, you should receive output of:

The root element is GetSearchResultsResponse.

Next, make sure that the actual request was successful:

...
       Element root = doc.getDocumentElement();

       Element successElement = 
             (Element)root.getElementsByTagName("Ack").item(0);
       if (successElement.getFirstChild().getNodeValue().equals("Success")) {
          System.out.println("Success!");
       } else {
          System.out.println("The request did not process properly.");
       }
   }
}

Once we have the root element, we can use getElementsByTagName to retrieve the Ack element. Because there's only one, we want the first item in that NodeList, which we then cast as an Element instead of a Node. Once we have the Ack element, we need to check the value of its contents.

Its contents, remember, consist of a child Node -- specifically, a Text Node. We retrieve that first child, get it's nodeValue, and see whether it's the text string Success. If not, we know something's gone wrong with the request. You can, of course, modify the application to return the error, but you can also view the request in your browser to see what the problem is.

Assuming all is well, find out how many results we're dealing with:

...
       Element successElement = 
             (Element)root.getElementsByTagName("Ack").item(0);
       if (successElement.getFirstChild().getNodeValue().equals("Success")) {
          System.out.println("Success!");
      
         NodeList results = 
                 root.getElementsByTagName("SearchResultItemArray");
         Element resultsElement = (Element)results.item(0);
         NodeList resultItems = 
                 resultsElement.getElementsByTagName("SearchResultItem");
         int numberOfResultItems = resultItems.getLength();

         Element paginationResults = 
               (Element)root.getElementsByTagName("PaginationResult").item(0);
         String totalResults = 
               paginationResults.getElementsByTagName("TotalNumberOfEntries")
                                .item(0).getFirstChild().getNodeValue();

        System.out.println("There are "+numberOfResultItems+
               " items in this result, out of a total of "+totalResults+".");

       } else {
          System.out.println("The request did not process properly.");
       }
   }
}

First, we're creating a NodeList out of the SearchResultItem children of the SearchResultItemArray element. (We could also have used getChildNodes() to accomplish this feat.) From there, we can get the length of the list to find out how many items we have.

That tells us how many results were in the current response, but to find out how many results exist in the entire database, we need to get the value of the TotalNumberOfEntries element.

If you were to run this application with an argument of, say "christmas", you should get a result something like:

Success!

There are 6 items in this result, out of a total of 6.

Once we know how many items we're dealing with, we can deal with them, extracting the appropriate information:

...
           NodeList resultItems = 
                 resultsElement.getElementsByTagName("SearchResultItem");
           int numberOfResultItems = resultItems.getLength();

           for (int thisItem = 0; thisItem < numberOfResultItems; thisItem++){

               Element thisItemElement = (Element)resultItems.item(thisItem);
               Element innerElement = 
                   (Element)thisItemElement.getElementsByTagName("Item").item(0);
               Element listingDetailsElement = 
                   (Element)innerElement.getElementsByTagName("ListingDetails").item(0);

               String endTime = 
                   listingDetailsElement.getChildNodes().item(1)
                                        .getFirstChild().getNodeValue();

               String itemURL = 
                    listingDetailsElement.getChildNodes().item(2)
                                         .getFirstChild().getNodeValue();

               Element titleElement = 
                    (Element)innerElement.getElementsByTagName("Title").item(0);
               String titleString = titleElement.getFirstChild().getNodeValue();

               Element sellingStatusElement = 
                    (Element)listingDetailsElement.getNextSibling();
               String bids = 
                    sellingStatusElement.getElementsByTagName("BidCount").item(0)
                                        .getFirstChild().getNodeValue();
               Element currentPriceElement = 
                    (Element)sellingStatusElement.getElementsByTagName("CurrentPrice")
                                                 .item(0);
               String currentPrice = currentPriceElement.getFirstChild().getNodeValue();
               String currency = 
                    currentPriceElement.getAttributeNode("currencyID").getNodeValue();

           }


         Element paginationResults = 
               (Element)root.getElementsByTagName("PaginationResult").item(0);
         String totalResults = 
               paginationResults.getElementsByTagName("TotalNumberOfEntries")
                                .item(0).getFirstChild().getNodeValue();

       } else {
          System.out.println("The request did not process properly.");
       }
   }
}

All of this is standard DOM manipulation. First we retrieve a reference to a specific Item element, and then we use DOM methods such as getChildNodes(), getFirstChild(), and getNextSibling() to retrieve specific pieces of information based on their positions in the XML document.

Finally, create and send the output:

...
               String currentPrice = currentPriceElement.getFirstChild().getNodeValue();
               String currency = 
                    currentPriceElement.getAttributeNode("currencyID").getNodeValue();

               System.out.println(
                    "<a href='"+itemURL+"'>"+titleString+"</a> "+currentPrice
                                         +" ("+currency+") - ends "+endTime+"<br />");
         }


         Element paginationResults = 
               (Element)root.getElementsByTagName("PaginationResult").item(0);
...

If you compile and run the application, it should look something like this:

[nicholaschase@spinel www]$ java ShowFile christmas
<a href='http://cgi.sandbox.ebay.com/ws/eBayISAPI.dll?ViewItem&item=450429
5322&category=617&ssPageName=WDVW&rd=1'><br />Claym
ation Christmas - Will Vinton New DVD! + Easter!</a> <br />15.5 (USD) - end
s 2006-01-03T14:35:50.000Z<br />
<a href='http://cgi.sandbox.ebay.com/ws/eBayISAPI.dll?ViewItem&item=450429
5470&category=617&ssPageName=WDVW&rd=1'><br />Red S
kelton's Christmas New DVD! Sealed</a> <br />3.5 (USD) - ends 2006-01-03
T14:41:21.000Z<br />

<a href='http://cgi.sandbox.ebay.com/ws/eBayISAPI.dll?ViewItem&item=450429
5510&category=617&ssPageName=WDVW&rd=1'><br />Claym
ation Christmas - Will Vinton New DVD! + Easter!</a> <br />15.5 (USD) - end
s 2006-01-03T14:43:09.000Z<br />
<a href='http://cgi.sandbox.ebay.com/ws/eBayISAPI.dll?ViewItem&item=450429
5665&category=617&ssPageName=WDVW&rd=1'><br />SONIC
 CHRISTMAS BLAST - DVD NEW 4 EPISODES</a> <br />4.95 (USD) - ends
 2006-01-03T14:48:14.000Z<br />

<a href='http://cgi.sandbox.ebay.com/ws/eBayISAPI.dll?ViewItem&item=450429
5666&category=617&ssPageName=WDVW&rd=1'><br />INSPE
CTOR GADGET SAVES CHRISTMAS NEW DVD 4 EPISODES</a> <br />4.9
5 (USD) - ends 2006-01-03T14:48:14.000Z<br />
<a href='http://cgi.sandbox.ebay.com/ws/eBayISAPI.dll?ViewItem&item=450429
5679&category=617&ssPageName=WDVW&rd=1'><br />A MAT
TER OF PRINCIPLE ~ NEW DVD CHRISTMAS W/ ALAN ARKIN</a> <br />1
0.95 (USD) - ends 2006-01-03T14:48:49.000Z<br />

Now we have a working application, but it can only access the sandbox, or test database. In order to access the production database, we need to "certify" the application. Time was that the "standard" certification process involved submitting your application for review by eBay, a process that took seven to ten days. That process is still in place, but if you're expecting less than 10,000 calls per month, you can "self-certify" your application and get access to the production database immediately.

To self certify, make sure that your application satisfies the certification requirements, and then fill out the self certification form, providing basic information about your application.

Once you receive your confirmation code, follow the same process you used to retrieve your sandbox keys to get your production keys. Once you have them, go back to the token tool and retrieve tokens for the production environment.

Now try your request with the production URL:

http://rest.api.ebay.com/restapi?CallName=GetSearchResults&RequestToken=yourTokenHere&RequestUserId=yourUseridHere&Query=toy%20boat&Schema=1

You should see results similar to those from the sandbox database, but with a couple of significant differences:

<?xml version="1.0" encoding="UTF-8"?>

<GetSearchResultsResponse xmlns="urn:ebay:apis:eBLBaseComponents">
  <Timestamp>2005-12-29T16:56:23.790Z</Timestamp>
  <Ack>Success</Ack>
  <Version>439</Version>

  <Build>e439_core_Bundled_2176832_R1</Build>
  <SearchResultItemArray>
    <SearchResultItem>
      <Item>
        <ItemID>7377084130</ItemID>

        <ListingDetails>
          <StartTime>2005-12-24T08:56:34.000Z</StartTime>
          <EndTime>2005-12-29T08:56:34.000Z</EndTime>
          <ViewItemURL>http://cgi.ebay.com/ws/eBayISAPI.dll?ViewItem&item=7377084130&category=29564&rd=1</ViewItemURL>

        </ListingDetails>
        <SellingStatus>
          <BidCount>10</BidCount>
          <CurrentPrice currencyID="USD">18.5</CurrentPrice>
        </SellingStatus>

        <Site>US</Site>
        <Title>KOSTA BODA 2005 CHRISTMAS TREE ORNAMENT</Title>
        <ListingType>Chinese</ListingType>
        <Currency>USD</Currency>

        <GiftIcon>0</GiftIcon>
        <SiteHostedPicture>
          <GalleryType>Gallery</GalleryType>
        </SiteHostedPicture>
        <VendorHostedPicture>

          <GalleryURL>http://thumbs.ebay.com/pict/7377084130.jpg</GalleryURL>
          <GalleryType>Gallery</GalleryType>
        </VendorHostedPicture>
        <SubTitle></SubTitle>

        <PaymentMethods>PayPal</PaymentMethods>
        <Country>US</Country>
        <ShippingDetails>
          <ShippingType>Flat</ShippingType>

          <DefaultShippingCost>5.99</DefaultShippingCost>
        </ShippingDetails>
        <SearchDetails>
          <BuyItNowEnabled>false</BuyItNowEnabled>
        </SearchDetails>

      </Item>
      <SearchResultValues>Picture</SearchResultValues>
    </SearchResultItem>
...
  </SearchResultItemArray>
  <ItemsPerPage>100</ItemsPerPage>

  <PageNumber>1</PageNumber>
  <HasMoreItems>true</HasMoreItems>
  <PaginationResult>
    <TotalNumberOfPages>1333</TotalNumberOfPages>

    <TotalNumberOfEntries>133222</TotalNumberOfEntries>
  </PaginationResult>
  <CategoryArray/>
</GetSearchResultsResponse>

First, notice that the production version is different from the sandbox application version. eBay tracks versions based on this number, and requires compatibility up to a particular version number at any given time. Second, notice that a large percentage of "live" items also include photos. We can conditionally add this information to the application:

import javax.xml.parsers.DocumentBuilder;
import javax.xml.parsers.DocumentBuilderFactory;
import org.w3c.dom.Document;
import org.w3c.dom.Element;
import org.w3c.dom.NodeList;
import org.w3c.dom.Node;

public class ShowFile {

   public static void main (String args[]) {

       String requestToken = your token here;
       String requestUserId = your actual eBay ID here;

       String query = args[0];

       String docString = "http://rest.api.ebay.com/restapi?CallName=GetSearchResults"+
             "&RequestToken="+requestToken+
             "&RequestUserId="+requestUserId+
             "&Query="+query+
             "&Schema=1";

       Document doc = null;
       try {
           DocumentBuilderFactory dbf = 
                    DocumentBuilderFactory.newInstance();
           DocumentBuilder db = dbf.newDocumentBuilder();
           doc = db.parse(docString);
       } catch (java.io.IOException e) {
           System.out.println("Can't find the file");
       } catch (Exception e) {
           System.out.print("Problem parsing the file.");
       }

       Element root = doc.getDocumentElement();
       Element successElement = 
             (Element)root.getElementsByTagName("Ack").item(0);
       if (successElement.getFirstChild().getNodeValue().equals("Success")) {
      
           NodeList results = 
                 root.getElementsByTagName("SearchResultItemArray");
           Element resultsElement = (Element)results.item(0);
           NodeList resultItems = 
                 resultsElement.getElementsByTagName("SearchResultItem");
           int numberOfResultItems = resultItems.getLength();

           if (numberOfResultItems > 3){
               numberOfResultItems = 3;
           }

           for (int thisItem = 0; thisItem < numberOfResultItems; thisItem++){

               Element thisItemElement = (Element)resultItems.item(thisItem);
               Element innerElement = 
                   (Element)thisItemElement.getElementsByTagName("Item").item(0);
               Element listingDetailsElement = 
                   (Element)innerElement.getElementsByTagName("ListingDetails").item(0);

               String endTime = 
                   listingDetailsElement.getChildNodes().item(1)
                                        .getFirstChild().getNodeValue();

               String itemURL = 
                    listingDetailsElement.getChildNodes().item(2)
                                         .getFirstChild().getNodeValue();

               Element titleElement = 
                    (Element)innerElement.getElementsByTagName("Title").item(0);
               String titleString = titleElement.getFirstChild().getNodeValue();

               Element sellingStatusElement = 
                    (Element)listingDetailsElement.getNextSibling();
               String bids = 
                    sellingStatusElement.getElementsByTagName("BidCount").item(0)
                                        .getFirstChild().getNodeValue();
               Element currentPriceElement = 
                    (Element)sellingStatusElement.getElementsByTagName("CurrentPrice")
                                                 .item(0);
               String currentPrice = currentPriceElement.getFirstChild().getNodeValue();
               String currency = 
                    currentPriceElement.getAttributeNode("currencyID").getNodeValue();


               String pictureURL = "nopicture.gif";
               NodeList pictureElements = 
                         innerElement.getElementsByTagName("VendorHostedPicture");
               if (pictureElements.getLength() > 0){
                    NodeList pictures = ((Element)pictureElements.item(0))
                                            .getElementsByTagName("GalleryURL");
                    if (pictures.getLength() > 0) {
                        pictureURL = ((Element)pictures.item(0)).getFirstChild().getNodeValue();
                    }
               }

               System.out.println(
                    ">a href='"+itemURL+"'>>img src='"+pictureURL+"' border='0' />>br />"+
                              titleString+">/a> >br />"+currentPrice
                              +" ("+currency+") - ends "+endTime+">br />");
         }

       } else {
          System.out.println("The request did not process properly.");
       }
   }
}

First off, notice that you need to use the production information for the request. Second, while we can limit the number of responses right in the request -- and, in fact, for bandwidth reasons this is the preferred way of handling it -- we can also limit the number of items returned by the application. Finally, we're creating a URL for the thumbnail, starting with a default image if no image is provided. From there we look for the VendorHostedPicture element, which may not actually be there. If, however, it is there, we look for the GalleryURL element, and if it's present, set the pictureURL to the value of it's text node child. Whatever this value works out to be, we're adding it to an img in the response. Now if we run the application, we should see a response similar to:

[nicholaschase@spinel www]$ java ShowFile christmas
<a href='http://cgi.ebay.com/ws/eBayISAPI.dll?ViewItem&item=6466664912&category=309&rd=1'><img src='nopicture.gif' border='0' /><br />Touched by an Angel - A Christmas Miracle (1997, VHS)</a> <br />1.99 (USD) - ends 2005-12-29T08:50:22.000Z<br />
<a href='http://cgi.ebay.com/ws/eBayISAPI.dll?ViewItem&item=5649127337&category=3488&rd=1'><img src='nopicture.gif' border='0' /><br />L089 Senegal Christmas, Noel Luxury Proof Imperf.</a> <br />19.99 (USD) - ends 2005-12-29T08:50:27.000Z<br />

<a href='http://cgi.ebay.com/ws/eBayISAPI.dll?ViewItem&item=8245629512&category=113339&rd=1'><img src='https://thumbs.ebay.com/pict/8245629512.jpg' border='0' /><br />Wedding/Holiday/Christmas White Rose Pew Bows Set of 12</a> <br />8.95 (USD) - ends 2005-12-29T08:50:33.000Z<br />

You can add this output to a web page by converting this application to a servlet or JSP. If that's not an option for you -- say, if you are on a shared hosting plan, as I am -- you can also add the output to a PHP page using the passthru function:

<html>
<head><title>EBay Information</title></head>
<body>
<?php

passthru("/usr/local/java/bin/java -cp /home/nicholaschase/www ShowFile christma
s");
?>
</body>
</html>

The end result is a page similar to figure 2: