Getting Started with Search in the eBay Shopping API
Specifying XML Results with an HTTP POST Request

In this tutorial you use PHP to write a FindItems POST request to search for eBay listings based on a keyword. You specify that the response to your call is in XML format.

This tutorial shows how easy it is to use the eBay Shopping API. For notes about the tutorial and the eBay Partner Network, please see Notes and Next Steps. For additional resources, please see Additional Resources.

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

Simple search code

There are three steps:

Step 1: Set up and make the FindItems call

Step 2: Add code to make the call and display the response

Step 3: Run the code

The complete code in PHP_SearchGS_XML_XML.zip requires that you substitute your production appid for "MyAppID". In this tutorial, the equivalent of the sample in that zip file is MySample.php.

Step 1: Set up the FindItems call

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

Please install Apache HTTP Server and install PHP 5. PHP 5 includes the SimpleXML extension. In this tutorial, the PHP sample file will be stored at the following location: C:\Program Files\Apache Software Foundation\Apache2.2\htdocs.

This tutorial uses a POST that is functionally similar to the following URL (for an eBay Shopping API call):
http://open.api.ebay.com/shopping?appid=MyAppID&version=517&siteid=0&callname=FindItems&QueryKeywords=ipod&responseencoding=XML.

In the tutorial, you always must substitute your appid for "MyAppID" and remove all spaces and new-line characters. The following table contains the values you will use for your call:

To create the initial code for your Shopping API call:

Create a new file with the following text. Save the file at C:\Program Files\Apache Software Foundation\Apache2.2\htdocs\MySample.php.

<html>
<head>
<title>
eBay Search Results for <?php echo $query; ?>
</title>
</head>
<body>
<h1>eBay Search Results for <?php echo $query; ?></h1>
<?php echo $results;?>
</body>
</html>

Add the following PHP function to your code, directly after </html>. This function will build and make your FindItems call.

<?php

function constructPostCallAndGetResponse($endpoint, $query)
{
    // create the xml request that will be POSTed
    $xmlRequest  = "<?xml version=\"1.0\" encoding=\"utf-8\"?>";
    $xmlRequest .= "<FindItemsRequest xmlns=\"urn:ebay:apis:eBLBaseComponents\">";
    $xmlRequest .= "<QueryKeywords>";
    $xmlRequest .= $query;
    $xmlRequest .= "</QueryKeywords></FindItemsRequest>";

    $session  = curl_init($endpoint);                       // create a curl session

    curl_setopt($session, CURLOPT_POST, true);              // POST request type
    curl_setopt($session, CURLOPT_POSTFIELDS, $xmlRequest); // set the body of the POST
    curl_setopt($session, CURLOPT_RETURNTRANSFER, true);    // return values as a string - not to std out
    $headers = array(
      'X-EBAY-API-CALL-NAME: FindItems',
      'X-EBAY-API-SITE-ID: 0',                                 // Site 0 is for US
      'X-EBAY-API-APP-ID: MyAppID',
      'X-EBAY-API-VERSION: 515',
      "X-EBAY-API-REQUEST-ENCODING: XML",    // for a POST request, the response by default is in the same format as the request
      'Content-Type: text/xml;charset=utf-8',
    );
    curl_setopt($session, CURLOPT_HTTPHEADER, $headers);    //set headers using the above array of headers

    $responseXML = curl_exec($session);                     // send the request
    curl_close($session);

    return $responseXML;  // returns a string
} // function
?>

Review the values used for your FindItems call. The following table describes the values you are using, in the code above, for your FindItems call.

Standard value	Sample value	Description
X-EBAY-API-APP-ID	MyAppID	The appid you obtain by joining the eBay Developers Program.
X-EBAY-API-VERSION	515	The API version that your application supports.
X-EBAY-API-SITE-ID	0	The numeric value for the eBay site with the items you want information about, e.g. the site ID of the US site is 0.
X-EBAY-API-CALL-NAME	FindItems	The name of the call you are using, e.g. FindItems.
X-EBAY-API-REQUEST-ENCODING	XML	Specifies that the input format is XML.

Call-Specific Value	Sample value	Description
QueryKeywords	ipod	A query that specifies a search string.

For error reporting and to set initial variables, add the following code at the very beginning of MySample.php.

<?php

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

$query = 'ipod';  // Supply a query

$endpoint = 'http://open.api.ebay.com/shopping?';  // URL to call

Step 2: Add code to make the call and display the response

In this step you will add code to make the call and then display the items returned.

As described in Step 1, the URL that is functionally similar to the POST request in this tutorial is http://open.api.ebay.com/shopping?appid=MyAppID&version=517&siteid=0&callname=FindItems&QueryKeywords=ipod&responseencoding=XML.

In MySample.php, after the last line above (where $endpoint is set to a URL value), add the following code:

// Construct the FindItems Shopping API POST call.
// Load the call and capture the document returned.
$resp = simplexml_load_string(constructPostCallAndGetResponse($endpoint, $query));

// Check to see if the response was loaded, else print an error
if ($resp) {
	$results = '';

    // If the response was loaded, parse it and build links
    foreach($resp->Item as $item) {
        $link  = $item->ViewItemURLForNaturalSearch;
        $title = $item->Title;

		// For each SearchResultItem node, build a link and append it to $results
		$results .= "<a href=\"$link\">$title</a><br/>";
	}
}
// If there was no response, print an error
else {
	$results = "Oops! Must not have gotten the response!";
}
?>

Save the MySample.php file.

Step 3: Run the code

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

The result should look similar to the following:

Simple search code

Congratulations! You have used the eBay Shopping API to search for items on eBay and to display the search results to a user.

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

Notes and Next Steps

This section contains notes about the tutorial and suggestions.

eBay Partner Network (eBay Affiliate Program)

You can earn money with the eBay Partner Network (eBay Affiliate Program)! Send users to eBay, and earn money for new active users (ACRUs) and successful transactions. 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 FindItems in the Call 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.

Additional Resources

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

Call Reference

Getting Started Guide

Call Structure

User-Contributed Notes

Getting Started with Search in the eBay Shopping API Specifying XML Results with an HTTP POST Request