Using the API Test Tool

The eBay API is an extensive system that allows you to call data directly from the eBay servers. This is in contrast to a feed which is a standalone file containing references to items on eBay. Contained in the eBay developer program website, there is an extensive API test tool to explore the results of API calls using any and all available parameters. This can be used directly by developers, or by an affiliate to test basic API calls before having a developer integrate it into a website. A full introduction to the API http://developer.ebay.com/quickstartguide/default.aspx

The API Test Tool https://developer.ebay.com/DevZone/build-test/test-tool/default.aspx

SETTING UP AN API CALL

On the left of the tool page there is a number of choices to make to dictate what type of API call you are making and to where. I’ll run through each section, its purpose and when to use it here:

Sandbox/Production Choice

The Sandbox will use testing databases that do not contain live items and data. Production will use the live databases containing items currently listed on eBay. Use the sandbox when testing calls that will post to eBay such as those in the Trading API. This can be switched to production for going live once it has been tested. Use Production when extracting information, for example when searching for items, categories and sellers.

Key Set

This section will be automatically populated once you have set up your developer keys using your developer account page.  https://developer.ebay.com/DevZone/account/default.aspx

Selecting an API

There are a number of different API's available that do different things. The Shopping and Finding API’s are for searching for items available for sale. The Trading API is for listing and selling items, and so forth. A comprehensive guide to what each API does can be found at the documentation center (http://developer.ebay.com/support/docs/default.aspx). For the purposes of this article, we will mostly be covering using the Finding API.

Selecting an API Call

Within each different API, there is a selection of calls that you can make to that API. For example, in the Finding API, the most useful and common call is findItemsAdvanced, which offers the most flexibility in finding items. However, the Finding API all has other calls, such as to find items by their category or store name. Again, a comprehensive guide to what each call can do for you can be found at the Documentation Center (http://developer.ebay.com/support/docs/default.aspx).

Selecting a Template

After you have set up your call type and are ready to make a call, you will be able to change the search criteria of the call you’ve set up. This is simply a quick way to add some example search criteria fields into the request field on the right. These can be changed or removed at any time. Selecting “Full/Generic” will give you blank fields in your XML Request box.  Selecting “Partial/Pre-Filled” will give you some basic example fields that have already been populated. This is useful for people new to the tool to get used to searching with it. If you’d like to see an example that includes the ePN tracking parameters, select the “Full/generic” option and you’ll find them in the “<affiliate>” tags.

Select Call Variation/Fields to Include

The contents of this box are dictated by the template you have selected, but again, it is just a quick way to add search fields into your XML Request box. If you have a “Full/Generic” template, you will be given the option of adding in only required fields, or adding in every possible field. If you select every possible field, they will be added into your XML request box on the right. What you can do from here is go through each one and decide whether or not you want to use it. For example, you might want to search using keywords but have no need to specify a category. What you can do is take this line: <keywords>string</keywords> and add in your keywords as needed. Then take this line: <categoryId>string</categoryId> and just delete the line from the box. Working with all the possible fields in this way allows you to see all possibilities and make full use of a given API call.

Selecting a Call Request Version

As a general rule, this does not need to be changed. This is only for very specific circumstances such as when an API has had changes made to it and caused problems.

Selecting a Site ID

A number of different eBay sites exist for different purposes, like different countries or for eBay Motors in the US. Items listed in the UK will be contained within the UK site, Germany in the DE site. Different territories will have different sets of categories based on language and categorical needs between countries. An API call can only be made to a single eBay site, so the site needs to be specified. Making a call to multiple sites will require multiple API calls.

SETTING THE REQUEST VALUES

Once you have set up the tool with the API call you wish to make, you can move on to the right side of the tool page to change the request values of your call. I will run through what each of the sections is for here:

Web Service URI (Endpoint)

This is the web URL of the API you are using. The “Select an API” box will automatically populate this for you, but you can change it manually if you wish.

HTTP Headers

Again, these will be automatically populated by the choices you have made by setting up your API call on the left. You can manually change these but there is no need to.

XML Request

This box contains the data that will be posted to the API and determine what to return. The search parameters are contained within XML tags, which means like this: <entriesPerPage>2</entriesPerPage>. The values inside the tags (in this case “2”) are what you change to make your call. It is useful to use the pre-filled examples to get a feel for how to use this part of the tool, and full documentation for each parameter can be found in the documentation center (http://developer.ebay.com/support/docs/default.aspx).

VIEWING THE RESULTS

Once you have chosen all your parameters, submit the query and your results will be shown in the call response box. This will be in the XML format and look something like this:

If you get no results consider changing your call to be less specific. Once you are satisfied with the call, you can move on to integration into a website  (https://developer.ebay.com/quickstartguide/).

USAGE EXAMPLE

Here I will run through an example of using the API tool to achieve a goal: to return a list of blue shorts available to buy immediately in the UK.

1. Select the “Production” environment because we are searching for items listed on eBay.

2. Select the Finding API, because we are searching for items.

3. Use the findItemsAdvanced call so we can specify advanced parameters for finding a specific type of item

4. Set the “Full, generic” template and include all possible fields in the call. This will allow us to easily use whatever parameters we need and remove any we don’t need.

5. Set the site ID to UK.

6. Set the Category to use the shirts category.  The eBay categories page (http://listings.ebay.co.uk/) can help you find the category ID you need. The CGMlab category tool (http://ebay.cgmlab.co.uk/tool-categorytree.php) can also provide details on every available category.

7. Set item filters to include Auction listings with Buy It Now, Fixed Price items, and eBay Stores inventory items. These are all items that can be bought immediately. Full list of item filters available for findItemsAdvanced (http://developer.ebay.com/DevZone/Finding/CallRef/types/ItemFilterType.html).

8. Set an aspect filter to only find items that have “Main Colour” of “Blues”. The possible aspects within a given category can be found out by looking at the category page, here in this case (http://clothes.shop.ebay.co.uk/Shorts-/15689/i.html?LH_LocatedIn=1&_armrs=1&_dmd=1&_mdo=Clothes-Shoes-Accessories&_mspp=&_pcats=1059%2C11450&_salic=3). Further documentation on aspect filters is available in the call documentation (http://developer.ebay.com/DevZone/Finding/CallRef/findItemsAdvanced.html#Request.aspectFilter).

9. Specify your ePN tracking parameters. The network ID for eBay Partner Network is 9, and use the tracking ID tag for your campaign ID. The “<geoTargeting>” tag is for future use and you can set the value to 0.

10. Delete any unused fields from the XML Request. Since we opted to include all possible fields to make it easier to add what we wanted, there will be a lot of empty unused fields. These can affect your results and need to be trimmed. The full call should now look something like this:

11. Once the call has been made the results are returned. All the details about the call and items returned are available here including error messages if the call has failed. From here you can change any parameters to the set up of the call, resubmitting and experimenting to see what you can do to get better results.

IMPLEMENTATION OPTIONS

The API Test Tool is a great way to view the API calls and iterate through the options to get the to call that best meets your needs. There are many options for how you actually implement the API call, and several formats for the call itself. Sample Finding API calls for XML and standard URL format can be found here:

http://developer.ebay.com/DevZone/finding/CallRef/findItemsAdvanced.html#Samples

For more general information on all of your options for request and response formats, see here: http://developer.ebay.com/DevZone/finding/Concepts/MakingACall.html

The API Test Tool is a great way to view the API calls and iterate through the options to get the to call that best meets your needs. There are many options for how you actually implement the API call, and several formats for the call itself. Sample Finding API calls for XML and standard URL format can be found here: http://developer.ebay.com/DevZone/finding/CallRef/findItemsAdvanced.html#Samples

For more general information on all of your options for request and response formats, see here: http://developer.ebay.com/DevZone/finding/Concepts/MakingACall.html