Your Global Marketplace for B2B Surplus




A u c t i o n   L i s t i n g



Date: October 4th 2000
Version: 1.0


Liquidation.com
202.467.6868 ph
202.467.4575 fx
http://www.liquidation.com/
Table of Contents
Introduction

In order for Liquidation.com to initiate and sustain effective relationships with its partners, it is highly desirable to have a single, consistent data format, which can be used to interchange data with those partners. To this end, many Liquidation.com products are XML enabled. This document specifies the XML Document Type Definitions (DTD) that must be used to interface with Liquidation.com's live auction data.

Not much about XML needs to be known to parse Liquidation.com's Auction Listing data feed. You can find a good deal of information on XML on the web. See éhttp://www.w3.org/XMLû for exhaustive information. If you're using Perl, you can also find information at éhttp://www.perlxml.com/û.

Overview

The Auction Listing data feed provided by Liquidation.com allows auction aggregators to access Liquidation.com's live database of open auctions for the purposes of searching Liquidation.com's marketplace.

Intended Audience

It is assumed that the reader of this document is familiar with HTML requests and the methods necessary to read an XML package contents (nodes in the tree). If you need further information on XML for your specific platform, please read the articles available on éhttp://www.xml.com/û, which cover all major software platforms and parser implementations.

Auction Listing URL

The URL for the Auction Listing GET requests is:

http://platform.liquidation.com/auction_listing/index.xml

The feed is composed of a single unlinked XML page generated once a day at 6:00AM EST. Clients may fetch this document by use of standard HTTP 1.1 GET requests.

Auction Listing Specification

This is the DTD for an auction listing (or set of listings) that you would download from our site is as follows: 


<!DOCTYPE auction_listing [
  <!ELEMENT auction_listing ( item+ ) >
  <!ATTLIST auction_listing version NMTOKEN #REQUIRED >
  <!ELEMENT bids ( #PCDATA ) >
  <!ELEMENT category ( #PCDATA ) >
  <!ELEMENT close_time ( #PCDATA ) >
  <!ELEMENT currency ( #PCDATA ) >
  <!ELEMENT description ( #PCDATA ) >
  <!ELEMENT high_bid ( #PCDATA ) >
  <!ELEMENT high_bidder ( #PCDATA ) >
  <!ELEMENT item (url, item_id, start_time, close_time,
    category, title, description, bids, quantity,
    start_price, high_bid, currency, seller,
    high_bidder, region, zip_code, picture_url?, 
    )>
  <!ELEMENT item_id ( #PCDATA ) >
  <!ELEMENT picture_url ( #PCDATA ) >
  <!ELEMENT quantity ( #PCDATA ) >
  <!ELEMENT region ( #PCDATA ) >
  <!ELEMENT seller ( #PCDATA ) >
  <!ELEMENT start_price (#PCDATA) >
  <!ELEMENT start_time ( #PCDATA ) >
  <!ELEMENT title ( #PCDATA ) >
  <!ELEMENT url ( #PCDATA ) >
  <!ELEMENT zip_code ( #PCDATA ) >
]>
Here's a filled in example with all of the usual fields. Note, an auction listing will contain multiple <item> nodes: 


<auction_listing version='1.0'>
   <item>
	<url>http://www.liquidation.com/auction/view?id=1</url>
	<item_id>123456</item_id>
	<start_time>2000-09-21 19:35:48</start_time>
	<close_time>2000-10-21 20:35:48</close_time>
	<category>2</category>
	<title>Some large furry things</title>
	<description><![CDATA[A <B>very</B> nice large furry thing that will
		             complement <I>any</I> home.]]></description>
	<bids>2</bids>
	<quantity>1</quantity>
	<start_price>100.00</start_price>
	<high_bid>105.00</high_bid>
	<currency>USD</currency>
	<seller>jdoe</seller>
	<high_bidder>jdoe2</high_bidder>
	<region>Washington, DC, US</region>
	<zip_code>20032</zip_code>
   </item>
</auction_listing>
What all this means is that we're creating a document of type éauction_listingû, and that there are one or more items in an auction_listing. The version number in the auction list tag is required, and is currently '1.0'. Each item consists of a list of elements containing Parsed Character Data. Note that item descriptions are likely to contain HTML markup, and as such are enclosed within é<![CDATA[]]>û tags.

    1. url the URL used to directly access this item's listing
    2. item_id the unique item identifier on our site
    3. start_time the date and time the auction began
    4. close_time the date and time the auction will close
    5. category the category id the item appears in
    6. title the short, descriptive title of the item
    7. description the long description of the item, usually containing HTML
    8. bids the number of bids the item has received so far
    9. quantity the number of lots available in the auction
    10. start_price the first bid of the opening price set by the seller
    11. high_bid the highest bid so far received for the item
    12. currency the ISO three-letter currency code
    13. seller the user name of the seller
    14. high_bidder the the user name of the current high bidder
    15. region the geographic location of the item
    16. zip_code the ZIP/Postal Code for the item's region
    17. picture_url the URL of the image if the auction has a picture (optional)
In addition to what the DTD specifies, we have a few additional requirements:

  1. If picture_url is missing, it is assumed there is no picture of this item. This URL will point to the raw image, as we resize the image for display in our auction view pages.


  2. The date and time fields are specified in 24 hour SQL time format (YYYY-MM-DD HH:MM:SS, adjusted to GMT/UTC).

  3. Prices will be numeric with a two-digit fraction: 9999.99. No commas or currency signs. If the price is only fractional (or zero), there must be a zero to the left of the decimal point (0.00, or 0.25, for example). The two-digit fraction must be present even if it makes no sense for the currency (as in lira or yen).


  4. The currency code is the appropriate ISO 4217 standard three-letter code. "USD" for US dollars, "CAD" for Canadian dollars, "GBP" for British pounds, etc. This complete list is a good reference.


  5. The category field is a numeric id representing a placement category. The category id to category name map is as follows: 

    
1	Apparel and Textiles
2	Apparel and Textiles > Apparel and Clothing
3	Apparel and Textiles > Textile, Yarn and Garments
4	Apparel and Textiles > Small Textile and Apparel Machinery
5	Consumer and Retail Merchandise
6	Consumer and Retail Merchandise > General Retail Merchandise
7	Consumer and Retail Merchandise > Sporting Goods
8	Consumer and Retail Merchandise > Electronics
9	Consumer and Retail Merchandise > Food and Related
10	Consumer and Retail Merchandise > Health and Beauty
11	Consumer and Retail Merchandise > Household Goods
12	Consumer and Retail Merchandise > Software and Games
13	Military and Government Surplus
14	Military and Government Surplus > Military Surplus
15	Military and Government Surplus > Government Surplus
16	Office Supplies and Equipment
17	Office Supplies and Equipment > Office Equipment and Supplies
18	Office Supplies and Equipment > Electronics
19	Office Supplies and Equipment > Furniture and Fixtures
20	Office Supplies and Equipment > Computer Hardware
21	Construction Supplies and Related
22	Construction Supplies and Related > Construction Supplies
23	Construction Supplies and Related > Real Estate
24	Construction Supplies and Related > Construction Related Services
25	Other
26	Other > Industry Specific Equipment and Parts
27	Other > General Machinery, Equipment and Parts
28	Other > Automotive
29	Other > Transportation
30	Other > Real Estate
31	Other > Businesses
32	Other > Medical
33	Other > Services