Shopping API
 

Searching By Seller: Reviewing Information About A Seller

Note: This tutorial uses the findItemsAdvanced call in the Finding API.

Completed Code

The objective of this tutorial is to write an application that does the following:

When you complete the tutorial, you will have code that looks like this when it runs:

Search Results

This tutorial uses the findItemsAdvanced call from the Finding API and the GetUserProfile call from the Shopping API. Using these calls:

If the links you present to users (after making these calls) include affiliate tracking information, as described in this tutorial, you can earn money through the eBay Partner Network. For notes about the tutorial and the eBay Partner Network, see Notes and Next Steps. For additional resources, see Additional Resources.

Please join the eBay Developers Program. Note your Production AppID so you can substitute it in this tutorial where it says "INSERT_YOUR_APP_ID." This tutorial uses production data.

This tutorial contains the following steps:

Step 1: Set up basic files and folders

Step 2: Add code for making the GetUserProfile call and displaying the results

Step 3: Add code for making the FindItemsAdvanced call and displaying the results

Step 4: Add HTML and Javascript for the user interface

Step 5: Run the code

Please download PHP_FIA_GUP_Interm_NV_XML.zip and unzip it to a temporary location. Note that if you use this code, you must substitute your production AppID for "INSERT_YOUR_APP_ID". In this tutorial, the equivalent of the main file in that zip file is GetUserProfileFIA.php.

Step 1: Set up basic files and folders

In this step, you put two files and two folders into your htdocs folder. You also create your main PHP file and then write some initial code to set variables (for URL endpoint, for your AppID, and for other values).

If you haven't installed Apache HTTP Server and PHP 5, and set them up for Shopping API calls, see the following tutorial: Getting Started with Search in the eBay Shopping API: Specifying XML Results with an HTTP POST Request. Also see that tutorial for information about substituting your AppID for the AppID placeholder in the tutorial. In the current tutorial, sample code is stored at the following location: C:\Program Files\Apache Software Foundation\Apache2.2\htdocs.

  1. Copy two files and two folders into htdocs. After you download PHP_FIA_GUP_Interm_NV_XML.zip, and unzip the file to a temporary location, copy the js and css folders to C:\Program Files\Apache Software Foundation\Apache2.2\htdocs. Copy DisplayUtils.php to the same location. DisplayUtils.php contains 2 helper functions. Additionally, copy license.txt to the same location. Now, the contents of htdocs are the following:


    2. Name     Description
    DisplayUtils.php Contains 2 helper functions
    license.txt Contains a license for the code
    js folder Contains jQuery, a javascript library
    css folder Contains stylesheets and related files

  2. Create a blank file at C:\Program Files\Apache Software Foundation\Apache2.2\htdocs\GetUserProfileFIA.php. Add the following, which includes code to set some initial variables for the tutorial application. Substitute your Production AppID where it says "INSERT_YOUR_APP_ID." 
    <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">

<?php

require_once('DisplayUtils.php');  // functions to aid with display of information

//error_reporting(E_ALL);  // turn on all errors, warnings and notices for easier debugging

$sellerID='';
$pageResults='';

if(isset($_POST['SellerID']))
{
  $s_endpoint = 'https://open.api.ebay.com/shopping';  // Shopping
  $f_endpoint = 'https://svcs.ebay.com/services/search/FindingService/v1';  // Finding
  $responseEncoding = 'XML';   // Format of the response
  $s_version = '667';   // Shopping API version number
  $f_version = '1.4.0';   // Finding API version number
  $appID   = 'YOUR_APP_ID'; //replace this with your AppID

  $debug   = true;
  $debug = (boolean) $_POST['Debug'];

  $sellerID  = urlencode (utf8_encode($_POST['SellerID']));   // cleanse input
  $globalID    = urlencode (utf8_encode($_POST['GlobalID']));

  $sitearray = array(
    'EBAY-US' => '0',
    'EBAY-ENCA' => '2',
    'EBAY-GB' => '3',
    'EBAY-AU' => '15',
    'EBAY-DE' => '77',);


  $siteID = $sitearray[$globalID];

  $pageResults = '';
  $pageResults .= getUserProfileResultsAsHTML($sellerID);
  $pageResults .= getFindItemsAdvancedResultsAsHTML($sellerID);

} // if

Back to Top

Step 2: Add code for making the GetUserProfile call and displaying the results

The objectives of this step are the following:

The GetUserProfile call obtains the seller's profile, including the feedback score. The GetUserProfile call also obtains a link to the seller's My World page. If you'd like to customize the code for GetUserProfile, see GetUserProfile.

  1. Review the main GetUserProfile fields that are used in the tutorial application. These values include the UserID field (which enables your application to retrieve information about a seller) and the affiliate parameters:

    Example of GetUserProfile Field Input or Output? Value to Your Application
    UserID Input Contains the ID of a seller whose information (e.g. the feedback and profile) might be desired by your application users
    IncludeSelector Input Enables your application to return the MyWorldURL and MyWorldLargeImage fields (by specifying Details in the IncludeSelector field)
    trackingpartnercode, trackingid, affiliateuserid Input These URL parameters enable affiliate tracking so you can earn money through the eBay Partner Network. The call response will contain a link that, if presented to a user by your application, will enable affiliate tracking of their activity on eBay.
    UniquePositiveFeedbackCount, UniqueNegativeFeedbackCount Output Used to determine the seller's positive-feedback percent
    MyWorldLargeImage, MyWorldURL Output Enable you to provide a user with profile-related information about a seller
    RegistrationDate Output Contains the date a user registered on eBay
  2. In GetUserProfileFIA.php, go the end of the existing code. Add the following getUserProfileResultsAsHTML function. The function includes code for a GetUserProfile call for obtaining detailed information about a seller. The response, which includes the My World URL, is displayed to the user. Due to the affiliate input parameters (see the table above), links returned in fields such as SellerItemsURL are affiliate-enabled. 
    function getUserProfileResultsAsHTML($sellerID) {
    global $siteID, $s_endpoint, $responseEncoding, $s_version, $appID, $debug;
    $results = '';

    $apicall = "$s_endpoint?callname=GetUserProfile"
		   . "&version=$s_version"
		   . "&siteid=$siteID"
		   . "&appid=$appID"
		   . "&UserID=$sellerID"
		   . "&IncludeSelector=Details,FeedbackHistory"   // need Details to get MyWorld info
		   . "&responseencoding=$responseEncoding";


    if ($debug) { print "<br />GetUserProfile call = <blockquote>$apicall </blockquote>"; }

    // Load the call and capture the document returned by the Shopping API
    $resp = simplexml_load_file($apicall);

    if ($resp) {
        if (!empty($resp->User->MyWorldLargeImage)) {
            $myWorldImgURL = $resp->User->MyWorldLargeImage;
        } else {
            $myWorldImgURL = 'https://pics.ebaystatic.com/aw/pics/community/myWorld/imgBuddyBig1.gif';
        }
        $results .= "<table><tr>";
        $results .= "<td><a href=\"" . $resp->User->MyWorldURL . "\"><img src=\""
                  . $myWorldImgURL . "\"></a></td>";
        $results .= "<td>Seller : $sellerID <br /> ";
        $results .= "Feedback score : " . $resp->User->FeedbackScore . "<br />";
        $posCount = $resp->FeedbackHistory->UniquePositiveFeedbackCount;
        $negCount = $resp->FeedbackHistory->UniqueNegativeFeedbackCount;
        $posFeedBackPct = sprintf("%01.1f", (100 * ($posCount / ($posCount + $negCount))));
        $results .= "Positive feedback : $posFeedBackPct%<br />";
        $regDate = substr($resp->User->RegistrationDate, 0, 10);
        $results .= "Registration date : $regDate<br />";

        $results .= "</tr></table>";

    } else {
        $results = "<h3>No user profile for seller $sellerID";
    }
    return $results;
} // function
  3. Save the GetUserProfileFIA.php file.

Back to Top

Step 3: Add code for making the findItemsAdvanced call and displaying the results

The objectives of this step are the following:

The findItemsAdvanced call can obtain items for sale by a seller. If you'd like to customize the code for findItemsAdvanced, see findItemsAdvanced.

  1. Review the primary input values in this tutorial application for dindItemsAdvanced. These values include the SellerID field (which enables your application to retrieve the seller's items) and the affiliate parameters. For information about the other inputs and outputs, see the FindItemsAdvanced tutorial on the Tutorials page.

    Example of findItemsAdvanced Field Input or Output? Value to Your Application
    SellerID Input Contains the ID of a seller whose listings are desired, or might be desired, by your application users
    trackingpartnercode, trackingid, affiliateuserid Input These URL parameters enable affiliate tracking so you can earn money through the eBay Partner Network. The call response will contain a link that, if presented to a user by your application, will enable affiliate tracking of their activity on eBay.
    IncludeSelector Input Enables you to specify an input selector (e.g., SearchDetails); include-selectors cause more fields to be returned
    ItemArray Output Contains the eBay items being sold by the seller specified in the SellerID input field
  2. In GetUserProfileFIA.php, go to the end of the existing code. Add the following getFindItemsAdvancedResultsAsHTML function. The function includes code for a FindItemsAdvanced call for specifying a user's choices of the following: seller ID, site ID, listing type, and sort order. The response, which includes information about items sold by the seller, is displayed to the user. Due to the affiliate input parameters (see the table above), links returned in fields such as ViewItemURLForNaturalSearch are affiliate-enabled. 
    function getFindItemsAdvancedResultsAsHTML($sellerID) {
  global $globalID, $f_endpoint, $responseEncoding, $f_version, $appID, $debug;

  $maxEntries = 3;

  $itemType  = urlencode (utf8_encode($_POST['ItemType']));
  $itemSort  = urlencode (utf8_encode($_POST['ItemSort']));

  $results = '';   // local to this function
  // Construct the FindItems call
  $apicall = "$f_endpoint?OPERATION-NAME=findItemsAdvanced"
       . "&version=$f_version"
       . "&GLOBAL-ID=$globalID"
       . "&SECURITY-APPNAME=$appID"   // replace this with your AppID
       . "&RESPONSE-DATA-FORMAT=$responseEncoding"
       . "&itemFilter(0).name=Seller"
       . "&itemFilter(0).value=$sellerID"
       . "&itemFilter(1).name=ListingType"
       . "&itemFilter(1).value=$itemType"
       . "&paginationInput.entriesPerPage=$maxEntries"
       . "&sortOrder=$itemSort"
       . "&affliate.networkId=9"        // fill in your information in next 3 lines
       . "&affliate.trackingId=123456789"
       . "&affliate.customId=456";

  if ($debug) { print "<br />findItemsAdvanced call = <blockquote>$apicall </blockquote>"; }

  // Load the call and capture the document returned by the Finding API
  $resp = simplexml_load_file($apicall);

  // Check to see if the response was loaded, else print an error
  if ($resp->ack == "Success") {
    $results .= 'Total items : ' . $resp->paginationOutput->totalEntries . "<br />";
    $results .= '<table id="example" class="tablesorter" border="0" cellpadding="0" cellspacing="1">' . "";
    $results .= "<thead><tr><th /><th>Title</th><th>Price     </th><th>Shipping     </th><th>Total     </th><th><!--Currency--></th><th>Time Left</th><th>End Time</th></tr></thead>";

    // If the response was loaded, parse it and build links
    foreach($resp->searchResult->item as $item) {
      if ($item->galleryURL) {
        $picURL = $item->galleryURL;
      } else {
        $picURL = "https://pics.ebaystatic.com/aw/pics/express/icons/iconPlaceholder_96x96.gif";
      }
      $link  = $item->viewItemURL;
      $title = $item->title;

      $price = sprintf("%01.2f", $item->sellingStatus->convertedCurrentPrice);
      $ship  = sprintf("%01.2f", $item->shippingInfo->shippingServiceCost);
      $total = sprintf("%01.2f", ((float)$item->sellingStatus->convertedCurrentPrice
                    + (float)$item->shippingInfo->shippingServiceCost));

        // Determine currency to display - so far only seen cases where priceCurr = shipCurr, but may be others
        $priceCurr = (string) $item->sellingStatus->convertedCurrentPrice['currencyId'];
        $shipCurr  = (string) $item->shippingInfo->shippingServiceCost['currencyId'];
        if ($priceCurr == $shipCurr) {
          $curr = $priceCurr;
        } else {
          $curr = "$priceCurr / $shipCurr";  // potential case where price/ship currencies differ
        }

        $timeLeft = getPrettyTimeFromEbayTime($item->sellingStatus->timeLeft);
        $endTime = strtotime($item->listingInfo->endTime);   // returns Epoch seconds
        $endTime = $item->listingInfo->endTime;

      $results .= "<tr><td><a href=\"$link\"><img src=\"$picURL\"></a></td><td><a href=\"$link\">$title</a></td>"
           .  "<td>$price</td><td>$ship</td><td>$total</td><td>$curr</td><td>$timeLeft</td><td><nobr>$endTime</nobr></td></tr>";
    }
    $results .= "</table>";
  }
  // If there was no search response, print an error
  else {
    $results = "<h3>No items found matching the $itemType type.";
  }  // if resp

  return $results;

}  // function

?>
  3. Save the GetUserProfileFIA.php file.

Back to Top

Step 4: Add HTML and Javascript for the user interface

In this step, you write HTML to provide the user with search options. You also provide an option for the user to view all items by the seller. Additionally, you provide javascript to enable the user to sort search results.

  1. In GetUserProfileFIA.php, go the end of the existing code and add the following. This code provides the user interface of your application. 
    <head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>GetUserProfile</title>
<script src="./js/jQuery.js"></script>
<script src="./js/jQueryUI/ui.tablesorter.js"></script>

<script>
  $(document).ready(function() {
    $("table").tablesorter({
      sortList:[[7,0],[4,0]],    // upon screen load, sort by col 7, 4 ascending (0)
      debug: false,        // if true, useful to debug Tablesorter issues
      headers: {
        0: { sorter: false },  // col 0 = first = left most column - no sorting
        5: { sorter: false },
        6: { sorter: false },
        7: { sorter: 'text'}   // specify text sorter, otherwise mistakenly takes shortDate parser
      }
    });
  });
</script>

</head>

<body>

<link rel="stylesheet" href="./css/flora.all.css" type="text/css" media="screen" title="Flora (Default)">

<form action="GetUserProfileFIA.php" method="post">
<table cellpadding="2" border="0">
  <tr>
    <th>SellerID</th>
    <th>Site</th>
    <th>ItemType</th>
    <th>ItemSort</th>
    <th>Debug</th>
  </tr>
  <tr>
    <td><input type="text" name="SellerID" value=""></td>
    <td>
      <select name="GlobalID">
        <option value="EBAY-AU">Australia - EBAY-AU (15) - AUD</option>
        <option value="EBAY-ENCA">Canada (English) - EBAY-ENCA (2) - CAD</option>
        <option value="EBAY-DE">Germany - EBAY-DE (77) - EUR</option>
        <option value="EBAY-GB">United Kingdom - EBAY-GB (3) - GBP</option>
        <option selected value="EBAY-US">United States - EBAY-US (0) - USD</option>
      </select>
    </td>
    <td>
      <select name="ItemType">
        <option selected value="All">All Item Types</option>
        <option value="Auction">Auction Items Only</option>
        <option value="FixedPriced">Fixed Priced Item Only</option>
      </select>
    </td>
    <td>
      <select name="ItemSort">
        <option value="BidCountFewest">Bid Count (fewest bids first) [Applies to Auction Items Only]</option>
        <option selected value="EndTimeSoonest">End Time (soonest first)</option>
        <option value="PricePlusShippingLowest">Price + Shipping (lowest first)</option>
        <option value="CurrentPriceHighest">Current Price Highest</option>
      </select>
    </td>
    <td>
    <select name="Debug">
      <option value="1">true</option>
      <option selected value="0">false</option>
      </select>
    </td>

  </tr>
  <tr>
    <td colspan="4" align="center"><INPUT type="submit" name="submit" value="Search"></td>
  </tr>
</table>
</form>

<?php
  print $pageResults;
  $allItemsURL = "http://search.ebay.com/_W0QQsassZ" . $sellerID;
  print "<p><a href=\"$allItemsURL\">See all items from this seller</a></p>";
?>

</body>
</html>
  2. Save the GetUserProfileFIA.php file.

Back to Top

Step 5: Run the code

The GetUserProfileFIA.php file is complete. Open the file in a browser (http://localhost/GetUserProfileFIA.php).

After you enter a seller ID and click Search, the result should look similar to the following:

Search Results

Congratulations! You have used the eBay Shopping API to enable a user to retrieve seller information and listings.

For information about the business benefits of using the eBay Developers Program and for other important information, please see the Quick Start Guide.

Back to Top

Notes and Next Steps

This section contains notes about the tutorial and suggestions.

eBay Partner Network (eBay Affiliate Program)

You may be able to earn money with the eBay Partner Network (eBay Affiliate Program). For more information, visit the eBay Partner Network. This tutorial contains affiliate-related code. The code is commented-out because affiliate functionality is not available in the Sandbox environment.

For information about the URL parameters for affiliate tracking, see the Affiliate URL Parameters and HTTP Header Values table.

About the Application

The sample provided with this tutorial was built and tested on a Windows 2000 Server platform using PHP 5.2.1 for Win32 and Apache 2.2.4 for Windows.

About the Call

See findItemsAdvanced and GetUserProfile in the API Reference for descriptions of all the input and output parameters and additional information.

Try different input parameters to change the search criteria, or modify the application to display additional fields.

Back to Top

Additional Resources

More information about the eBay Shopping API is available at these locations:

API Reference

Getting Started Guide

Call Structure

More information about the eBay Finding API is available at these locations:

API Reference

User Guide

Making a Call