Getting Started with the Finding API: Finding Items by Keywords

This tutorial shows how easy it is to use the eBay Finding API. In the tutorial, you build a simple PHP application to submit a findItemsByKeywords call to search for eBay listings based on a keyword query. The code constructs a URL-format HTTP GET call that returns the results in XML format. The code parses the XML and constructs a simple HTML page with data from the call response.

When you complete the tutorial, you'll have an application that looks like this when it runs:

Getting Started with the Finding API

For notes about the tutorial, additional resources, and suggestions for next steps, please see Notes and Next Steps.

What's in this Tutorial

This tutorial contains the following sections:

Complete Source Code
Before You Begin
Step 1: Set up the API call
Step 2: Add code to parse and display the call response
Step 3: Insert an indexed array of item filters
Step 4: Run the code
Notes and Next Steps
User-Contributed Notes

Complete Source Code

The completed code is provided as a downloadable ZIP file, GettingStarted_PHP_NV_XML.zip. You must replace instances of "MyAppID" in the tutorial code with your production AppID.

The sample code was built and tested on a Windows 2000 Server platform.

Before You Begin

There are a few prerequisites for completing this tutorial:

Join the eBay Developers Program and get your Access Keys.
Joining is free and you get 5,000 API calls a day just for joining! When you generate your application keys from your My Account page, note your Production AppID so you can substitute it in this tutorial where it says "MyAppID." This tutorial uses production data.
Install Apache HTTP Server.
Apache HTTP Server is a popular web server, capable of running PHP applications. Apache is easy to install and configure. The steps in this tutorial are written with the assumption you are using Apache. PHP is, however, compatible with most popular servers, so Apache is not strictly required. The tutorial code should run on any web server configured to support PHP.
Install PHP 5.
The code for this tutorial is written in PHP. PHP 5 includes the SimpleXML extension, which is required for this tutorial.

Step 1: Set up the findItemsByKeywords call

This step sets up the basic PHP code to construct the API request and the HTML code for displaying the results.

To create the initial code for your Finding API call:

Create a new PHP file, MySample.php, with the following code.
Save the file as MySample.php in the DocumentRoot directory of your Apache installation (e.g., C:\Program Files\Apache Software Foundation\Apache2.2\htdocs). The file includes the PHP container (<?php ... ?>) where you'll add the code to make an API request and parse the response. It also includes the HTML code to display the results of parsing the API call.
```
<?php

?>
<html>
<head>
<title>
eBay Search Results for <?php echo $query; ?>
</title>
<style type="text/css">body { font-family: arial,sans-serif;} </style>
</head>
<body>

<h1>eBay Search Results for <?php echo $query; ?></h1>

<table>
<tr><td>
<?php echo $results;?>
</td></tr>
</table>

</body>
</html>
```

Plan the values for the findItemsByKeywords input parameters.

Standard Parameter	Sample value	Description
OPERATION-NAME	findItemsByKeywords	The name of the call you are using. This is hard-coded to `findItemsByKeywords` in the following step.
SERVICE-VERSION	1.0.0	The API version your application supports.
SECURITY-APPNAME	MyAppID	The AppID you obtain by joining the eBay Developers Program.
GLOBAL-ID	EBAY-US	The eBay site you want to search. For example, the eBay US site (`EBAY-US`) or the eBay Germany site (`EBAY-DE`).

Call-Specific Parameter	Sample value	Description
keywords	harry potter	A query that specifies a search string. The `$SafeQuery` variable (added in the next step) will URL-encode your query keywords to replace spaces and special characters so the query will work in a URL request.
paginationInput.entriesPerPage	3	The maximum number of items to return in the response. This is hard-coded as 3 in the following step.

Add the code to construct the API request.

This code contains the following:

API request variables for input parameter values from the preceding step, including the query keywords and your AppID
API call variable, $apicall, constructed with values from the declared variables

Note: You must replace the "MyAppID" value for the $appid variable for the code to work with your Production AppID. You can retrieve your AppID from your My Account page.

Enter the following code directly after <?php.

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

// API request variables
$endpoint = 'http://svcs.ebay.com/services/search/FindingService/v1';  // URL to call
$version = '1.0.0';  // API version supported by your application
$appid = 'MyAppID';  // Replace with your own AppID
$globalid = 'EBAY-US';  // Global ID of the eBay site you want to search (e.g., EBAY-DE)
$query = 'harry potter';  // You may want to supply your own query
$SafeQuery = urlencode($query);  // Make the query URL-friendly


// Construct the findItemsByKeywords call 
$apicall = "$endpoint?";
$apicall .= "OPERATION-NAME=findItemsByKeywords";
$apicall .= "&SERVICE-VERSION=$version";
$apicall .= "&SECURITY-APPNAME=$appid";
$apicall .= "&GLOBAL-ID=$globalid";
$apicall .= "&keywords=$SafeQuery";
$apicall .= "&paginationInput.entriesPerPage=3";

The tutorial code is not yet ready to run. Proceed to the next step to add the code that submits the API request and parses the response.

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

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

Here is the URL used for your Finding API call, as described in Step 1:

http://svcs.ebay.com/services/search/FindingService/v1?OPERATION-NAME=findItemsByKeywords&SERVICE-VERSION=1.0.0&SECURITY-APPNAME=MyAppID&GLOBAL-ID=EBAY-US&keywords=harry+potter&paginationInput.entriesPerPage=3

The responseencoding=XML parameter causes the response data to be in XML format.

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

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

// 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) {
	$results = '';

    // If the response was loaded, parse it and build links
    foreach($resp->searchResult->item as $item) {
        $pic   = $item->galleryURL;
        $link  = $item->viewItemURL;
        $title = $item->title;

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

Save the MySample.php file.

This file is now runnable, but we're not done yet. Skip ahead to Step 4 to see what it looks like, or proceed to the next step to add item filters to the request.

Step 3: Insert an indexed array of item filters

This step adds code to add item filters to your request. Whenever you use repeating fields in a URL-format request, you must index the fields for them to be properly processed. The code you will add consists primarily of an array for item filter values and a function for indexing the array for use in the URL request.

Add an array for item filters.

Add the following array after the variable declarations (i.e., after the line starting with $SafeQuery). This array contains three item filters: MaxPrice, FreeShippingOnly, and ListingType.

$filterArray =
	array(
	  array(
		'name' => 'MaxPrice',
		'value' => '25',
		'paramName' => 'Currency',
		'paramValue'  => 'USD'),
	  array(
		'name' => 'FreeShippingOnly',
		'value' => 'true',
		'paramName' => '',
		'paramValue'  => ''),
	  array(
		'name' => 'ListingType',
		'value' => array('AuctionWithBIN','FixedPrice','StoreInventory'),
		'paramName' => '',
		'paramValue'  => ''),
	);

Add a function to build an indexed item filter array for use with a URL request.

Add the following code directly after the array added in the preceding step. This function parses the item filter array, formats the filters as indexed URL parameters, and sets their collective value as a variable, $urlfilter.

  // Build item filters URL array
  function buildURLArray ($filterArray) {
    global $urlfilter;
    global $i;
    // Iterate through each filter in the array
    foreach($filterArray as $itemFilter) {
      // Iterate through each key in the filter
      foreach ($itemFilter as $key =>$value) {
        $r = '0'; //A number that increments each time the above "for" loops;
        if(is_array($value)) { //if the 'value' var content is an array
          if($value != "") { //check to make sure the content isn't empty
            foreach($value as $j => $content) {
              $urlfilter .= "&itemFilter($i).$key($j)=$content";
            }
          }
        }
        else { // not an array, print contents of the 'value' container, no indexing needed
          if($value != "") {
            $urlfilter .= "&itemFilter($i).$key=$value";
          }
        }
        $r++;
      }
      $i++;
    }
    return "$urlfilter";
  } // End of buildURLArray function

buildURLArray($filterArray);

Add a variable declaration for the item filter index value to initialize its value as 0.
Add the following line to the variable section at the top of the file directly after the $SafeQuery entry.
```
$i = '0';  // Initialize the item filter index array to 0
```
Add the variable for the item filters to the end of the code used to construct the API call.
Add the following line to the end of the $apicall variable, directly after the line that add pagination to the call (&paginationInput.entriesPerPage=3).
```
$apicall .= "$urlfilter";
```
Save the MySample.php file.

The MySample.php file is complete! Proceed to the next step to see the results.

Step 4: Run the code

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

The result should look similar to the following:

Getting Started with the Finding API

Congratulations! You have used the eBay Finding 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 Business Benefits page.

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 Tracking section in the eBay Finding API Users Guide.

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

This tutorial is based on the findItemsByKeywords call. See findItemsByKeywords in the Call Reference for descriptions of all the input and output parameters and additional information.

If you want your application to display the assembled URL request that is being sent to eBay, add the following HTML code just before the closing body tag (i.e., </body>):

<p><b>API request used (click URL to view XML response):</b></p>
<p><a href="<?php echo $apicall;?>"><?php echo $apicall;?></a></p>

The tutorial code can be adapted easily to other Finding API calls by changing the OPERATION-NAME value to the call you want to use. Note that findItemsByCategory and findItemsByProduct do not support keywords as input.

What's Next

Here are some suggestions for ways you could modify or extend the tutorial code to learn more about the API and create a more interesting application:

Change the query or your item filter values to see how they affect the output
Modify the application to display additional fields
Try different input parameters, such as sortOrder, to control the results
Add more or different item filters
Programmatically populate the item filter array from UI interaction
See if you can adapt the item filter array and array indexing function for use with aspect filters

Additional Resources

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

Call Reference

Users Guide

Making an API Call

User-Contributed Notes

Share tips or code samples related to this call or document. Questions or observations are welcome, too.

eBay employees moderate these notes to ensure they're pertinent to the document and relevant to the community. Your submission will show up for all developers when it's activated by the moderator.

eBay Finding API Tutorial