eBay Shopping Web Services
Searching eBay with FindItemsAdvanced and GetUserProfile
for the JavaScript SDK

Introduction

In this tutorial, you create a small Javascript application that searches the eBay site for a specific seller's items that are ending soonest, as well as the seller's public eBay member information.

Once you've completed the basic example with one call, such as the FindItemsAdvanced tutorial, you can expand your skills and your application's complexity. This tutorial shows how simple it is to use two calls together to create a useful application. The application allows a user to input a seller's ID to retrieve the seller's basic information and five of the seller's active listings which are ending soon. To do so, the application uses the GetUserProfile and FindItemsAdvanced Shopping API calls. When you complete the tutorial, you will have an application that looks like this when it runs (for security reason user data is annonymized in following sample, when you run the sample with your user id, you will see related information there):

getUserProfile sample

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 Affiliate Program. For notes about the tutorial and the eBay Affiliate Program, see Notes and next steps.

There are just four steps:

Step 1: Set up and make the calls

Step 2: Add code to validate and format the response

Step 3: Add code to display the results

Step 4: Run the application

Notes and next steps

User comments

Complete sample code

This tutorial was designed to explain the GetUsersProfile sample files, located within the /samples directory of your JavaScript SDK, and to help you create your own applications based on these samples. Some of the steps may include a sub-set of the code that is actually in the sample, in order to keep the tutorial concise. Please compare the tutorial to the samples as you proceed.

Before you begin

There are some basic requirements for performing this tutorial:

Read the JavaScript SDK User Guide
Complete the FindItemsAdvanced JavaScript SDK sample
This sample uses GetUserProfile and FindItemsAdvanced shopping API calls, and builds on the Find Items Advanced tutorial.

Step 1: Set up and make the calls

The JavaScript SDK allows you to create an interactive JavaScript UI component that can access data on the eBay Servers.

To create the initial code for forming your JavaScript SDK Shopping API call:

Include the JS SDK and supporting files in the <script> section of the html page.

//Shopping.js is the file that includes the service interface that allows you to connect and retrieve
//data from the eBay Shopping Web Service. You need to include this path to retrieve data
//from the eBay servers.
<script TYPE='text/javascript' SRC='http://w-1.ebay.com/js/2.0/min/Shopping.js'></script>

//ItemListUI.js includes code to build UI to display list of items.
//Similarly, ProfileUI.js includes code to build a UI to display a seller's profile.
<script TYPE='text/javascript' SRC='ItemListUI.js'></script>
<script TYPE='text/javascript' SRC='ProfileUI.js'></script>

//eBayUtils.js includes supporting functions for GetUserProfile sample.
<script TYPE='text/javascript' SRC='eBayUtils.js'></script>

//GetUserProfileSample.js executes the Shopping API calls for the GetUserProfile SDK sample.
<script type="text/javascript" src="GetUserProfileSample.js">

//Set the baseUrl, so that you can dynamically download type files needed to execute the sample.
baseUrl: 'http://w-1.ebay.com/js/2.0/min/'

See the JavaScript SDK User's Guide for more information about the differences between dynamically downloading files and including them within your JavaScript programs directly.

List the files and resources required to execute the sample.

files: ['GetUserProfile.js', 'FindItemsAdvanced.js'],

resources:[].concat(com.ebay.shoppingservice.Shopping.getUserProfile, com.ebay.shoppingservice.Shopping.findItemsAdvanced),

Add the function call from the JS file and change the default user to a valid SellerID.
Add a function to call the JS function which will handle the business logic and replace the <insert SellerID here> with a valid eBay.com production SellerID. To find a valid SellerID, you can go to ebay.com and search for a popular item and use the SellerID from a returned item. We suggest you choose a seller with more than five active listings for the purposes of this sample. The image path should point to the user's MyWorld image. If the user has not added a My World image, add the path below and the default image will be used as the image in the top left corner of the sample widget.
```
function() {
	image = 'http://w-1.ebay.com/images/stockimage1.jpg';
	GetUserProfileSample.goSearch({g_userID: "<insert SellerID here>"});
	}
```
Open the GetUserProfileSample.js file and change the AppID to reflect your AppID.
In order to use the JS SDK, you will need to insert your eBay Developer AppID. In the provided sample, look for the following line and change the <insert your AppID here> text to reflect your AppID.
```
props["appId"] = "Your Appid" ;
```

Initialize the properties for TrackingID, TrackingPartnerCode, AffiliateUserID, and siteID

The code for the input properties look like this:

props["trackingid"] = "<Your tracking id>";
props["trackingpartnercode"] = "<Your tracking partner code>";
props["affiliateuserid"] = "<Your Affiliate UserID>";
//Place site id, default is 0 if you don't set
props["siteId"] = <Site ID>;

Create an instance of the shopping service configuration class and pass the properties in.
You create an instance of the com.ebay.shoppingservice.ShoppingConfig class and pass in the properties you just initialized:
```
var config = new com.ebay.shoppingservice.ShoppingConfig(props);
```
Create an instance of the shopping service and pass in the configuration.
The following code creates an instance of the com.ebay.shoppingservice.Shopping class:
```
var service = new com.ebay.shoppingservice.Shopping(this.config);
```
Gather the data you need to make each call and form the requests.
For a GetUserProfile request, you must include a UserID. IncludeSelector is also specified to request more details in the response; specifying IncludeSelector is optional. For more information about GetUserProfile, see the GetUserProfile Shopping call reference.
```
// GetUserProfile request with UserID = userID and IncludeSelector = Details, FeedbackHistory
var fiRequest = new com.ebay.shoppingservice.GetUserProfileRequestType({userID: userID, 
	includeSelector: "Details,FeedbackHistory"});
```
To find five of the seller's active auction and store items sorted by ending time, use the query below. For more information about FindItemsAdvanced, see the FindItemsAdvanced Shopping call reference.
```
// FindItemsAdvanced request with SellerID = userID, ItemSort = EndTime (default),
// ItemType = AllItemTypes, MaxEntries = 5
var request = new com.ebay.shoppingservice.FindItemsAdvancedRequestType({sellerID: userID, 
	itemSort: com.ebay.shoppingservice.SimpleItemSortCodeType.EndTime,
	itemType: com.ebay.shoppingservice.ItemTypeCodeType.AllItemTypes, 
	maxEntries: 5});
```
You can see that we used the JS SDK to include Code Lists and enum types to declare the value for itemSort and itemType, as these parameters take special types belonging to the Shopping API, unlike sellerID and maxEntries which each take a String.

Make the calls and capture the call responses.

You can make a Shopping call by calling the service.<callName>(success callback function and failure callback function) as seen here:

// Execute a GetUserProfile request with the parameters configured above for fiRequest
    var url = service.getUserProfile(fiRequest,
    {object: this, success: this.getUserProfile, failure: this.onCallbackFailed});


    // Execute a FindItemsAdvanced request with the parameters configured above for request
    url = service.findItemsAdvanced(request,
    {object: this, success: this.onSomeItemsReturned, failure: this.onCallbackFailed});

In this sample, the success callback function for each call receives the call's response data and sends it to the display function of the UI.

Let's take a look at how this is done.

Step 2: Add code to validate and format the response

When you make an API call, the eBay web service returns data in its reponse. For instance, when you make a GetUserProfile call, user data comes back in a JSON/XML format, but the callback functions in the JavaScript SDK save the JSON/XML response data as a JavaScript object.

The next three sections show you how to create the callback functions. First, the response is validated. If the response is valid the call was successful and the response is formatted and stored so it can be displayed. If the response was not valid, the callback function needs to handle the exception.

Check to see if a valid response was returned.

If the a valid response was returned, the returned data result will not equal null:

// Check to see if the returned result is invalid
if (data.user === null) {
	...
}

// Check to see if the returned result is valid,
if (data.searchResult !== null) {
	...
}

Re-format and store the response as a JavaScript object, so the data can be displayed as .html data.
The following code saves the returned JSON name/value pairs as local variables, formats the results, and builds an HTML link for returned URLs. The example below shows how to do this with a returned user from a successful GetUserProfile response. In this example the user's store name and store url are extracted from the call response and stored in an array, to display in the UI.
```
 {
	var user = data.user;
	...
 var specs = [];
	...
	if (user.storeName) {
	nameValue = {};
	nameValue.key = "Store Name";
	if (user.storeURL) {
	nameValue.value = "<a href='" + user.storeURL + "' >" + user.storeName + "</a>";
	} else {
	nameValue.value = user.storeName;
	}
	specs.push(nameValue); 
	}
	args.specs = specs;
	return args; 
}
```
You return the results to indicate that the call was successful.

Report an error if no response was retrieved successfully.

If an invalid response was returned, the failure condition of the API call will call a function to generate and display an error message. In the sample below, insert a textbox which can call the sample again and displays the error message returned by the Shopping call.

this.onCallbackFailed = function(error) {
	
var src = this.div.innerHTML; 
if (!this.hasError) {
	this.hasError = true;
	src = "<input id='query' type='text' size='22' maxlength='30'><input onclick=
	'GetUserProfileSample.goSearch()'; type='image' src='http://w-1.ebay.com/images/go.gif'>";
}
	
src = "<div>" + error[0].longMessage + "</div>" + src;
	this.div.innerHTML = src; 
};

Now you're ready to display the results.

Step 3: Add code to display the results

Now that you have formatted the response and saved the data to an array, you want to display the data as a section within an .html document. This is about the simplest HTML page you can make, but it is a great base from which to build more interesting interfaces.

To present your results as an HTML page:

Add the JS code that displays the data in the HTML file's div tag area.

By setting the $this.div variable to the HTML document object that we created with the formatted JS SDK response, we display the JS SDK results to the matching div tag in GetUserProfileSample.html.

// ----------------------- JS --------------------------------
/**
* div to display seller's profile and items
* @type Element
*/
this.div = document.getElementById("userContent");
	
// Insert our HTML in the div tag userContent area
this.div.innerHTML = src; 

// ----------------------- HTML ------------------------------
<div id="userContent"></div>

Save your files.
Save your JavaScript file with a js file extension and your HTML file with a html file extension. For example, name the JS file GetUserProfileSample.js and the HTML file GetUserProfileSample.html.

Now you have a complete JS application that searches an eBay website for a specified seller and the seller's items, then displays the results on an HTML page as live links to Seller Info (eg. Feedback) and View Item pages of the seller's listings. Run it and see what happens!

Step 4: Run the application

As long as your web server is configured to work with JS, running your application is easy.

To run your application:

Deploy your JS and HTML files onto your web server.
Refer to your web server documentation for information on how to deploy files onto your web server.
Point your browser to the file.
The browser should display a simple HTML page with seller information and listings for the seller specified in your HTML document.
Click a link to see the View Item page for the given listing.

Congratulations! You now have a working application that uses eBay Shopping Web Services.

Notes and next steps

This section contains observations about the tutorial and offers some alternate ways to achieve similar or better results. We've also provided some suggestions about where you can go from here.

eBay Affiliate Program

The eBay Affiliate Program allows you to earn money by driving traffic to the eBay site using applications or widgets you create and post on your own web page. You can think of this as a way to enhance your existing business or create a new enterprise. With just a little effort, you can earn a lot of money.

Now that you have a working search application, you can earn money with the eBay Affiliate Program! Join the affiliate program now!

Once you have joined the eBay Affiliate Program, sign up for the Affiliate API Tier of the eBay Developers Program.

About the application

As noted at the beginning of the tutorial, we tried to keep things simple. The eBay community codebase contains many excellent samples that are more complex and many give you good ideas for ways to design your applications.

The sample provided with this tutorial was built and tested on a Windows 2003 Server platform using JS for Win32 and Microsoft IIS 5.0.

About the call

For the tutorial, we took a minimalist approach to input parameters. The GetUserProfile call is very powerful. It supports numerous input parameters, and the query supports AND/OR logic and wildcards. Visit the JavaScript Developer Center for links to documentation and additional information.

The API call made by this application looks like the following:

http://open.api.ebay.com/shopping?callname=GetUserProfile&callbackname=com.ebay.shoppingservice.Shopping.getUserProfileClosure0&responseencoding=JSON&callback=true&version=529&appId=<YourAppId>&UserID=<YourUserId>&IncludeSelector=Details%2CFeedbackHistory&client=js

If you replace <YourAppId> and <YourUserId> with your App ID and eBay user ID, you can paste this URL into your browser to receive the JSON response for the GetUserProfile call.

More About JavaScript with the eBay Shopping Web Service

If you're interested in learning more about building applications using JavaScript with the eBay Shopping Web Service, see Getting Started with Search: Specifying JSON Results in a Shopping API GET Request.

Additional resources

Here's a list of resources for the topics and technologies introduced in this tutorial:

User-Contributed Notes

In order to leave a comment in this section, you must view this Tutorial via the eBay web site: online version.

eBay Shopping Web Services Searching eBay with FindItemsAdvanced and GetUserProfile for the JavaScript SDK