Hack #109. Retrieve Details About a Listing

Use the GetItem API call to get listing details.

The GetItem API call is used to retrieve all the details of a listing, including the title, description, starting price, category, and about 180 other individual bits of information.

Here's a simple script that, when provided with the item number, returns the title, seller ID, amount of time left, number of bids, and the current price:

	#!/usr/bin/perl
	require 'ebay.pl';

	$item_id = shift @ARGV or die "Usage: $0 itemnumber";

	my $rsp = call_api({ Verb => 'GetItem', 
						DetailLevel => 0, 
								Id => $item_id 
	});

	if ($rsp->{Errors}) { 
	 print_error($rsp) 
	} else { 
	   my %i = %{$rsp->{Item}[0]}; 
	my ($price, $currency, $bids, $time_left, $seller, $title) = 
	  @i{qw/CurrentPrice CurrencyId BidCount TimeLeft Seller Title/};

	$d = $time_left->{Days}; 
		$h = $time_left->{Hours}; 
		$m = $time_left->{Minutes}; 
		$s = $time_left->{Seconds}; 
		$seller_id = $seller->{User}{UserId}; 
		$seller_fb = $seller->{User}{Feedback}{Score};

		print "Item #$item_id: $title\n";
print "For sale by $seller_id ($seller_fb)\n";
		print "Currently at $currency$price, $bids bids\n";

		if ($d > 0) { print "$d days, $h hours left.\n"; }
		elsif ($h > 0) { print "$h hours, $m minutes left.\n"; }
		elsif ($s > 0) { print "$m minutes, $s seconds left.\n"; }
		else { print "auction ended.\n"; }
	}

This script is fairly straightforward. The GetItem API call is submitted on line , and the desired fields are extracted on line . Naturally, you can specify any of the 180+ field names specified in the API documentation (look up GetItem → Return Values in the index), as long as the variables on the left side of the equals sign on line match up with the field names on the right.

Note that some variables are hashes (which eBay calls "container nodes"), from which relevant data must be extracted. For instance, in the documentation you'll see entries for TimeLeft as well as TimeLeft.Days, TimeLeft.Hours, TimeLeft.Minutes, and TimeLeft.Seconds. In Perl, these elements of the hash are accessed with the -> arrow (infix dereference) operator, as shown on line .

To use the script, simply specify the item number, like this:

	getitem.pl 3136272129

and you'll get output like this:

	Item #3136272129: Little Red Steam Shovel
	For sale by ebayhacker
	Currently at $71.00, 9 bids
	1 days, 22 hours left.

However, you'll find it much more useful when used in conjunction with other scripts, like the ones in "Automatically Keep Track of Auctions You've Won" [Hack #110] and "Automatically Keep Track of Items You've Sold" [Hack #112] .

Hacking the Hack

The DetailLevel field in the API call on line determines how much information is retrieved. In most cases, a value of 0 is sufficient. However, if you want to retrieve the description, you'll need to raise this to at least 2. See "Spellcheck All Your Listings" [Hack #116] for an example.

Provided that you're the seller or the high bidder and the auction is completed, you can retrieve the HighBidder.User.Email and Seller.User.Email fields by specifying a detail level of at least 8, as shown in "Automatically Keep Track of Items You've Sold" [Hack #112] .

The DetailLevel tag is used for most API calls, but its usage isn't necessarily the same for all of them. In most cases, a higher detail level will result in more data received (and more time taken), but for some API calls, a high detail level (usually 32 and above) is used for special "abbreviated" result sets. Regardless, if you're not getting the results you expect from an API call, make sure you supply the appropriate DetailLevel, as instructed by the API documentation.