| Note: This tutorial uses the FindItemsAdvanced call in the Shopping API, This call is being deprecated and will not be available after October 2011. 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:
There are three steps:
Step 1: Set up and make the FindItems call
The completed code requires that you substitute your production appid for instances, in code, of "MyAppID".
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:
<html> <head> <title>eBay Search Results</title> </head> <body> <h1>eBay Search Results</h1> </body> </html>
| 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. |
</body>.
</body>).
<!-- Use the value of your appid for the appid parameter below. -->
<script src="http://open.api.ebay.com/shopping?
appid=MyAppID
&version=517
&siteid=0
&callname=FindItems
&QueryKeywords=ipod
&responseencoding=JSON
&callback=true">
</script>
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.
<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._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("");
The MySample.html file is complete. Open the file in a browser. The result should look similar to the following:
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.
This section contains notes about the tutorial and suggestions.
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.
The sample provided with this tutorial was built and tested on a Windows 2000 Server platform.
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.
More information about the eBay Shopping API is available at these locations:
© 2011 eBay Inc. All rights reserved.
eBay and the eBay logo are registered trademarks of eBay Inc.
All other brands are the property of their respective owners.