Getting Started with Search in the eBay Shopping API
Specifying JSON Results

Note: This tutorial uses the FindItemsAdvanced call in the Shopping API, This call is being deprecated and will not be available after July 1, 2010. The functionality provided by the FindItems call will be supported in the new Finding API. If you're building new search applications, we recommend you start with the Finding API.

In this tutorial you use JavaScript to write a FindItems call to search for eBay listings based on a keyword. You specify that the response to your call is in JSON (JavaScript Object Notation) format.

JSON is an easy way to store name-value pairs and arrays.

This tutorial shows how easy it is to use the eBay Shopping API. The tutorial utilizes a single JavaScript function for displaying the results in a browser. The code in this tutorial is not meant for production use in an application.

For notes about the tutorial and the eBay Affiliate Program, 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, with response in JSON format

There are three steps:

Step 1: Set up and make the FindItems call

Step 2: Add code to parse and display the response

Step 3: Run the code

The completed code requires that you substitute your production appid for instances, in code, of "MyAppID".

Step 1: Set up the FindItems call

This tutorial uses the following URL to make a Shopping API call:
http://open.api.ebay.com/shopping?appid=MyAppID&version=517&siteid=0&callname=FindItems&QueryKeywords=ipod&responseencoding=JSON&callback=true.

This URL works, and retrieves data, when you substitute your appid for "MyAppID" and remove all spaces and new-line characters.

In this tutorial, you must substitute your appid for instances in code of "MyAppID".

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.

To create the initial code for your Shopping API call:

Create a new text file, C:\MySample.html, containing the following HTML code:

<html>
<head>
<title>eBay Search Results</title>
</head>
<body>
<h1>eBay Search Results</h1>
</body>
</html>

Plan the values you will use for the FindItems input parameters. For more information about standard parameters, see the Standard URL Parameters and HTTP Header Values table.

Standard Parameter	Sample value	Description
appid	MyAppID	The appid you obtain by joining the eBay Developers Program.
version	517	The API version that your application supports. For information about functionality added with each API version, see the Shopping API Release Notes.
siteid	0	The numeric value for the eBay site with the items you want information about, e.g. the siteid of the US site is 0.
callname	FindItems	The name of the call you are using, e.g. FindItems.
responseencoding	JSON	Specifies that the output format is JSON.
callback	true	Specifies wrapping of response in a call to a _cb_FindItems function.

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

Add the following code directly before </body>.

This code contains the input parameters from the step above, including the query keyword and your appid (substitute your production appid where it says "MyAppID.").

After MySample.html is complete, this code will make a FindItems call when a user opens the file.

Please remember to put the code directly before the closing body tag (</body>).
```


<script src="http://open.api.ebay.com/shopping?

appid=MyAppID

&version=517

&siteid=0

&callname=FindItems

&QueryKeywords=ipod

&responseencoding=JSON

&callback=true">

</script>
```

Step 2: Add code to store and display the response

As described in Step 1, the URL used for your Shopping API call is http://open.api.ebay.com/shopping?appid=MyAppID&version=517&siteid=0&callname=FindItems&QueryKeywords=ipod&responseencoding=JSON&callback=true. The callback=true parameter causes the response data to be wrapped in a call to a _cb_FindItems function (but knowledge of this is not necessary for completing the tutorial).

In this step you will add an empty _cb_FindItems function to MySample.html, along with a div tag used by that function. Then you will add code to the function that will build an array of the items returned and then display the items for a user.

In C:\MySample.html, after <h1>eBay Search Results</h1>, add the following code:
```
<div id="results"></div>

<script>

function _cb_FindItems(root)
{

}

</script>
```
You have named the function _cb_FindItems because your callback=true input will cause the response data to be wrapped in a call to a _cb_FindItems function.

Inside the _cb_FindItems function, add the following code. This code for inside the _cb_FindItems function builds an array of the items returned. The code also puts the array into a string for display using the div tag.

  var items = root.Item || [];
  var html = [];
  for (var i = 0; i < items.length; ++i)
  {
    var item = items[i];
    var title = item.Title;
    var viewitem = item.ViewItemURLForNaturalSearch;

    if (null != title && null != viewitem)
    {
      html.push('<a href="' + viewitem + '">' + title + '</a><br/>');
    }
  }
  document.getElementById("results").innerHTML = html.join("");

Save the MySample.html file.

Step 3: Run the code

The MySample.html file is complete. Open the file in a browser. The result should look similar to the following:

Simple search code, with response in JSON format

Congratulations! You have used the 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.

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 JSON Results