Basic REST Request

The eBay API offers both REST and SOAP interfaces for its API. The REST portion, however, only offers search access.

The following code will make a hard-coded request against the eBay Sandbox API, and display the results to the screen, restExample.php:

 <?php   header("Content-Type: application/xml");   $endPoint = "http://rest.api.sandbox.ebay.com/restapi";   $requestToken   = "oVAr7OhSbdw%3D**%2Bs1d4ta8quAac9G3rvTuhs8IPvg%3D";   $requestUserId  = "wroxuser";   $searchTerms    = "boat";   $fullEndPoint = $endPoint . "?RequestToken={$requestToken}&RequestUserId=     {$requestUserId}&Query={$searchTerms}&CallName=GetSearchResults";   $results =  file_get_contents($fullEndPoint);   echo $results; ?> 

The first line sets the Content-Type for the output. Because the code will print the resulting XML directly to the screen, not only is this the right thing to do, but it will help ensure that it is displayed attractively. The next three lines define constants for the request. The requestToken is the token you received when you logged in with your Sandbox user account, and the requestUserId is simply the username associated with that account. searchTerms are the keywords you want to search for (remember to URL-encode anything you enter, spaces in particular). Finally, the endpoint URL is constructed, the request is made, and the results are relayed.

The endpoint the program retrieves is as follows:

 http://rest.api.sandbox.ebay.com/restapi?RequestToken=oVAr7OhSbdw%3D**%2Bs1d4ta8quA ac9G3rvTuhs8IPvg%3D&RequestUserId=wroxuser&Query=boat&CallName=GetSearchResults 

And the server returns the following response:

 <?xml version="1.0" encoding=" utf-8" ?> <eBay>   <EBayTime>2005-07-19 18:07:48</EBayTime>   <Search>     <Items>       <Item>         <Id>4503294022</Id>         <Title><![CDATA[Boat Captain Anchor Nautical Canvas Sailboat Pillow NEW]]>           </Title>         <SubtitleText><![CDATA[]]></SubtitleText>         <CurrencyId>1</CurrencyId>         <Link><![CDATA[http://cgi.ebay.com/ws/eBayISAPI.dll?ViewItem&item=           4503294022&category=20563]]></Link>         <CurrentPrice>9.99</CurrentPrice>         <LocalizedCurrentPrice>$9.99</LocalizedCurrentPrice>         <BINPrice>US $0.00</BINPrice>         <BidCount>0</BidCount>         <StartTime>2005-07-14 19:43:26</StartTime>         <EndTime>2005-07-21 19:43:26</EndTime>         <BillPointRegistered>0</BillPointRegistered>         <ItemProperties>           <BoldTitle>0</BoldTitle>           <Featured>0</Featured>           <Gallery>1</Gallery>           <GalleryFeatured>0</GalleryFeatured>           <GalleryURL><![CDATA[http://thumbs.ebay.com//pict/4503294022.jpg]]>             </GalleryURL>           <Picture>1</Picture>           <Highlight>0</Highlight>           <Border>0</Border>           <New>0</New>           <BuyItNow>0</BuyItNow>           <IsFixedPrice>0</IsFixedPrice>           <Type>1</Type>           <Gift>0</Gift>           <CharityListing>0</CharityListing>           <MotorsGermanySearchable>0</MotorsGermanySearchable>         </ItemProperties>       </Item>       <Item>         <Id>4503294023</Id>         <Title><![CDATA[Sailboat Boat Nautical Canvas Accent Bed Throw           Pillow]]></Title>         <SubtitleText><![CDATA[]]></SubtitleText>         <CurrencyId>1</CurrencyId>         <Link><![CDATA[http://cgi.ebay.com/ws/eBayISAPI.dll?ViewItem&item=           4503294023&category=20563]]></Link>         <CurrentPrice>9.99</CurrentPrice>         <LocalizedCurrentPrice>$9.99</LocalizedCurrentPrice>         <BINPrice>US $0.00</BINPrice>         <BidCount>0</BidCount>         <StartTime>2005-07-14 19:43:26</StartTime>         <EndTime>2005-07-21 19:43:26</EndTime>         <BillPointRegistered>0</BillPointRegistered>         <ItemProperties>           <BoldTitle>0</BoldTitle>           <Featured>0</Featured>           <Gallery>1</Gallery>           <GalleryFeatured>0</GalleryFeatured>           <GalleryURL><![CDATA[http://thumbs.ebay.com//pict/4503294023.jpg]]>             </GalleryURL>           <Picture>1</Picture>           <Highlight>0</Highlight>           <Border>0</Border>           <New>0</New>           <BuyItNow>0</BuyItNow>           <IsFixedPrice>0</IsFixedPrice>           <Type>1</Type>           <Gift>0</Gift>           <CharityListing>0</CharityListing>           <MotorsGermanySearchable>0</MotorsGermanySearchable>         </ItemProperties>       </Item>     </Items>     <Count>2</Count>     <HasMoreItems>0</HasMoreItems>     <PageNumber>1</PageNumber>     <GrandTotal>2</GrandTotal>   </Search> </eBay> 

The response, while verbose, does have a pretty basic structure, and the key information should be pretty easy to pick out. Within the Search branch, the Items branch holds all of the relevant search results within Item. Most of the values within that branch are self-explanatory, but a few are explained in more detail shortly. After the Items branch concludes, Count indicates the number of items returned in this response. HasMoreItems is a binary value indicating if there are more results available on another page. PageNumber indicates the page of this result, and GrandTotal indicates the total number of results available from all pages.

Some of the elements contained in each Item include the following:

• Id — A unique identifier for the item within the eBay system.

• CurrencyID — An integer that represents the native currency for the auction. The integers and the currency they represent include the following:

  • 1 — US Dollar ($)

  • 2 — Canadian Dollar (C $)

  • 3 — UK Pound Sterling (GBP)

  • 5 — Australian Dollar (AU $)

  • 7 — Euro (EUR)

  • 13 — Swiss Franc (CHF)

  • 41 — Taiwanese Dollar (NT $)

• LocalizedCurrentPrice — Returns the highest bid on the item, taking into account the currency of the item as well as the current location of the requestor (which can be specified in a more complex query). So, an item up for sale within the United States (and under the U.S. currency) viewed from someone with another location (say Canada) would have a localized price of US $20.00, whereas a client within the United States would simply see $20.00.

• BINPrice — This is the Buy It Now price. A bidder willing to pay the full Buy It Now price may end the auction immediately.

• BillPointRegistered — Bill Point is a payment system eBay used to offer. It is no longer used, so the value will always be zero.

• IsFixedPrice — A binary value. A 1 indicates that the item is for sale at a set price and a 0 indicates a regular auction.

• Type — An integer that indicates the type of auction that is being run. eBay offers several auction types beyond the normal. The integer and type of auctions are as follows:

  • 0 — Unknown auction type

  • 1 — Chinese auction

  • This is the standard auction type that you likely already associate with eBay. A single item is offered for sale, and a time frame is set. Bids are placed competitively during that time frame; at the end, the individual that has placed the highest bid is awarded the item at the highest bid price.

  • 2 — Dutch auction

  • In a Dutch auction, two or more items are placed up for sale, in which bidders can place a bid not only for an amount per item, but also the number of items desired (for example, you could place a bid for $100, and state that you desire 3 items [at $100 each]). At the end of the auction, items are awarded to the highest bidder, then the second highest, and so on, at the individual bidder's price.

  • 5 — Live auction

  • Similar to a Chinese auction, except the auction takes place both on eBay and in a live setting where non-eBay members may also bid on the item.

  • 6 — Ad Type auction

  • An advertisement for a real estate listing designed to generate leads rather than bids. This is a nonpurchase listing.

  • 7 — eBay Stores Inventory (fixed-price items).

  • Similar to fixed-price items, except items are listed only within the seller's store, not within a general eBay category.

  • 8 — Personal Offer auction

  • A special type of listing where the seller offers a specific item at a set price to another eBay user. This is a Second Chance offer, used by the seller to offer an item to a nonwinning bidder when the winning bidder didn't complete the transaction.

  • 9 — Fixed-Price item (combined with Buy It Now)

  • One or more items are offered for sale at a fixed price — there is no progressive bidding. Buyers may purchase an item or several items at a set price and complete the transaction immediately. The listing ends either when the duration is exhausted or when all of the available items are sold.

• CharityListing — Depreciated. A binary value, with a 1 indicating that the seller has chosen to donate a percentage of the proceeds of the sale to a selected nonprofit organization, and a 0 of course indicating that the full purchase price will be kept by the seller.

• MotorsGermanySearchable — A depreciated value, used to indicate that the item was dual listed with mobile.de.

As you have seen, it takes very little code to make a simple search query against the server, and the results returned are quite verbose (and only two items returned with the preceding code; most searches I tried returned 0 or the maximum of 100).

Note 

The eBay Sandbox is populated entirely by people testing their applications; it is not automatically populated with anything. As such, you can't rely on anything being present you if you didn't create it yourself.