Listing Ebay auctions in Drupal - Part 1 basic PHP

Before I begin I'd like to point out a couple of things. First I have barely scratched the surface of Ebay's APIs.There is so much that's possible that I do not yet fully understand. I encourage everyone to take a look at Ebay's developer docs to get an idea of the scope of the APIs available.

Also, I haven't been able to find any contributed modules that provide integration between Ebay and Drupal. The closest I've found is this thread discussing a possible specification: http://drupal.org/node/119986

My goal for this post is to describe how to use Ebay's search API to find and list relevant auctions by keyword in Drupal.

Getting Started

If you haven't already done so you will need to create a developer account with Ebay and get a set of production app keys. To do this you'll need to register an account on http://developer.ebay.com/.

AppID for the win

When you set up a production app you get three keys: DEVID, AppID and CertID. Of the three the AppID is all that's required to get search results from Ebay. Once you have your AppID, jot it down, you're going to need it shortly.

Ebay API calls and SOAP

Most of Ebay's API is SOAP based. Fortunately you can avoid the hassles associated with SOAP entirely if all your app is doing is searching available auctions. Ebay provides a GET based interface for their search-oriented API calls like FindItemsAdvanced which is what we will be using.

REALLY getting started

Preliminary BS out of the way, let's write some code. We'll start by setting up some variables.

/**
 * find auctions by keyword
 */
function ebay_search($keywords, $maxentries = 3) {

  $appID = '<your appID here>';

  //base url + api call
  $base = 'http://open.api.ebay.com/shopping?callname=FindItemsAdvanced';
 
  $encoding = '&responseencoding=XML';
  $siteid = '&siteid=0';
  $version = '&version=517';
  $keywords = '&QueryKeywords=' . $keywords;
  
  //put it all together and we have a working URL
  $query = $base . $encoding . $appid . $siteid . $version . $keywords;

}

There's a bit going on here but it's pretty straightforward. $Base, $encoding & $version are hardcoded default values taken from Ebay's developer docs and should Just Work. $siteid is worthy of more attention as this defines which ebay site (US, Canada, etc) you're fetching results for.

The code above is set to Ebay US (siteid 0). If you wish to change this to a different site you will need to look up the siteid for the Ebay site you want to use.

Fetching results

Ebay returns XML so we can use the simplexml_load_file() PHP function to do our dirty work for us.

  $response = simplexml_load_file($query); //get the goodies

  if($response) {
    //we have a response, parse it
    foreach($response->SearchResult->ItemArray->Item as $item){
       //display the auction item
       $content .= '<h2>' . $item->Title . "</h2>";        //auction title 
       $content .= '<img src="' . $item->GalleryURL  . '">'; //single image thumbnail
    }
  }

  return $content;

Full code

/**
 * find auctions by keyword
 */
function ebay_search($keywords, $maxentries = 3) {

  $appID = '';

  //base url + api call
  $base = 'http://open.api.ebay.com/shopping?callname=FindItemsAdvanced';
 
  $encoding = '&responseencoding=XML';
  $siteid = '&siteid=0';
  $version = '&version=517';
  $keywords = '&QueryKeywords=' . $keywords;
  
  //put it all together and we have a working URL
  $query = $base . $encoding . $appid . $siteid . $version . $keywords;

  $response = simplexml_load_file($query); //get the goodies

  if($response) {
    //we have a response, parse it
    foreach($response->SearchResult->ItemArray->Item as $item){
       //display the auction item
       $content .= '<h2>' . $item->Title . "</h2>";        //auction title 
       $content .= '<img src="' . $item->GalleryURL  . '">'; //single image thumbnail
    }
  }

  return $content;
}

Example of data returned

The example above outputs the auction title linked to the auction page and a thumbnail, but there is a lot more data available. Here's an example of what's returned by Ebay:

Successul search with results

 <?xml version="1.0" encoding="UTF-8"?>
<FindItemsAdvancedResponse xmlns="urn:ebay:apis:eBLBaseComponents">
   <Timestamp>2009-12-03T20:01:10.586Z</Timestamp>
   <Ack>Success</Ack>
   <Build>E643_CORE_BUNDLED_10272615_R1</Build>
   <Version>643</Version>
   <SearchResult>
    <ItemArray>
     <Item>
      <ItemID>290365278883</ItemID>
      <EndTime>2009-12-30T16:02:30.000Z</EndTime>
      <ViewItemURLForNaturalSearch>http://cgi.ebay.com/snip</ViewItemURLForNaturalSearch>
      <ListingType>FixedPriceItem</ListingType>
      <GalleryURL>http://thumbs4.ebaystatic.com/pict/2903652788838080_2.jpg</GalleryURL>
      <PrimaryCategoryID>63790</PrimaryCategoryID>
      <PrimaryCategoryName>Collectibles:Knives, Swords &
 Blades:Folding Knives:Modern (1970 - Now):Factory Manufactured:Boker</PrimaryCategoryName>
      <BidCount>4</BidCount>
      <ConvertedCurrentPrice currencyID="USD">12.95</ConvertedCurrentPrice>
      <ListingStatus>Active</ListingStatus>
      <TimeLeft>P26DT20H1M20S</TimeLeft>
      <Title>BOKER Magnum Razor/One Arm Jack Knife  **SC111**</Title>
      <ShippingCostSummary>
       <ShippingServiceCost currencyID="USD">0.0</ShippingServiceCost>
       <ShippingType>Flat</ShippingType>
       <ListedShippingServiceCost currencyID="USD">0.0</ListedShippingServiceCost>
      </ShippingCostSummary>
     </Item>
    </ItemArray>
   </SearchResult>
   <PageNumber>1</PageNumber>
   <TotalPages>26</TotalPages>
   <TotalItems>26</TotalItems>
   <ItemSearchURL>http://search.ebay.com/ws/search
/SaleSearch?DemandData=1&fsop=32&satitle=boker+razor&
lt;/ItemSearchURL>
  </FindItemsAdvancedResponse>

Successful search with no results found

<FindItemsAdvancedResponse>
<Timestamp>2009-12-03T20:27:41.476Z</Timestamp>
<Ack>Success</Ack>
<Build>E643_CORE_BUNDLED_10272615_R1</Build>
<Version>643</Version>
<PageNumber>1</PageNumber>
<TotalPages>0</TotalPages>
<TotalItems>0</TotalItems>
−
<ItemSearchURL>
http://search.ebay.com/ws/search/SaleSearch?DemandData=1&fsop=32&satitle...
</ItemSearchURL>
</FindItemsAdvancedResponse>

A quick note on auction images and descriptions

The auction description and urls of associated photos aren't returned by FindItemsAdvanced. To get this additional information you will need to use GetSingleItem.

/**
 * retrieve detailed information on a single auction item
 */
function _ebay_get_item($itemID){
  $baseURL = 'http://open.api.ebay.com/shopping?';
  $callname = 'callname=GetSingleItem';
  $appid = '&appid=' . variable_get('ebay_appid', NULL);
  $encoding = '&responseencoding=XML';
  $extra = '&siteid=0&version=517';
  $id = '&ItemID=' . $itemID;
  $selectors = '&IncludeSelector=Description,ItemSpecifics';

  $query = $baseURL . $callname . $encoding . $appid . $extra . $id . $selectors;

  drupal_set_message($query);
  $resp = simplexml_load_file($query);
  $item = theme('ebaylink_list_item', 'full',  $resp->Item);
  return $resp;
}

The astute reader has no doubt been wondering wtf all of this has to do with Drupal. Not much at the moment. The example code could easily be wrapped in a block or used as part of a larger module. It's looking like this post is going to be a three parter, so in the next installment I plan on covering some of the search variants available (search by seller id, category, etc). The third part will be a writeup on building a module based on the ebay search API.