At the Forge - eBay Web Services

Once you have gotten through the registration nightmare, you can make queries. The REST API is well documented and is quite straightforward to use. First, let's look at a simple program that sees how many matches we can find to a particular text string. The program, shown in Listing 1, is written in Ruby and is similar to some of the Amazon- and Google-searching programs presented during the past few months.

#!/usr/bin/ruby

require 'net/http'
require 'rexml/document'

if ARGV.length == 0
puts "#{$0}: You must enter at least one argument."
  exit
end

output = ""

# Iterate through each of our arguments
ARGV.each do |query_string|

output << "Searching for: #{query_string}\n"

  # Put together an eBay parameter string
  ebay_params = {'CallName' => 'GetSearchResults',
    'RequestToken' => 'XXX',
    'RequestUserId' => 'YYY',
    'Schema' => 1,
    'ItemTypeFilter' => 3,
    'SearchInDescription' => 1,
    'StoreSearch' => 3,
    'DetailLevel' => 3,
    'Query' => query_string}.map {|key,value|
"#{key}=#{value}"}.join("&")

  # Ask eBay what it knows about our query_string
  ebay_response = Net::HTTP.get_response('rest.api.ebay.com',
                                           '/restapi?' << ebay_params)

  xml = REXML::Document.new(ebay_response.body)

  # Get basic information
  how_many_matches =
xml.root.elements["PaginationResult/TotalNumberOfEntries"].text

output << "Number of matches: #{how_many_matches}\n"

end

# Show everyone what we've learned
puts output

The program begins by retrieving our search parameters, automatically placed in the ARGV variable. We iterate over each element of ARGV, calling each individual argument query_string. We then use a hash to create an easily understood set of name-value pairs, in which the hash keys are the parameter names and the hash values are the parameter values. We then use a bit of Ruby magic to combine them, first turning them into pairs with map, and then using join to connect the pairs together with &. In the end, we have a string we can pass to eBay's server.

In this particular example, we're using the Query method in the REST API. Query allows us to enter a text string, for which eBay will then search. The way that eBay has grown somewhat organically over the years becomes apparent when you use its Web services. You must explicitly indicate if you want to search in stores as well as auctions. We also must indicate whether we want auction items, fixed-price items or both. Thus, our example searches through all stores (because StoreSearch = 3), auctions and fixed-price items (ItemTypeFilter = 3), in descriptions as well as item titles (SearchInDescription = 1), and with a fair amount of detail returned (DetailLevel = 3).

We also indicate we want Schema = 1. This tells eBay we want to receive a response using eBay's new XML schema, rather than the older one that is now being deprecated.

We then take ebay_params, a string created from our name-value pairs, and pass it to Net::HTTP.get_response. This sends an HTTP request to eBay's server (rest.api.ebay.com), using the appropriate path (/restapi), followed by our name-value pairs.

When we get a response—and our sample code here assumes that we do receive a response—we expect that it is formatted in XML and parse it using Ruby's built-in REXML library. We grab the total number of entries in eBay's database containing this search string and use the text method to extract the text from between the <TotalNumberOfEntries> tags. Finally, the program displays its output, showing us how many items on eBay contain this text string.

The API is relatively fast, allowing us to perform lookups for a particular string in relatively short time. That said, popular search strings can take far longer than rare words. A search for an ISBN took 1–2 seconds on my computer and indicated how many sellers were offering that ISBN for sale. A search for the term auction, not surprisingly, took more than 30 seconds to return a result and indicated that 29,458,603 sellers mentioned that term in the title or description. Obviously, the choice of search term, as well as the number of sellers and the quantity of text searched for that term, will have a significant effect on the performance of your application.

eBay's API makes it possible to perform Boolean searches of various types. Putting two words together within quotation marks (URL-encoded, of course) allows you to search for a phrase. You can search for two words in the same auction by linking them with commas.

You also can include and exclude particular sellers. If you are a seller on eBay, you might want to look at all of your items—or all of your competitors' items, ignoring yours. These functions make it easier to navigate through the complex world of eBay, which sells a staggering variety of goods from all over the world.