In this post we’re going to explore an example of how to begin working with the eBay finding API. At the end you should be able to take the core concepts introduced (along with the source code) and begin working with the API in your own projects.

There are a few use cases for using the finding API, which will help you to figure out whether it is the right choice for you. Typically (but not always), you would use the finding API to:

• Build a product inventory around some particular category.
• Augment your existing product offerings with those from eBay.
• Get extended details about particular products from the inventory.

With that said, let’s take a look at a simplified PHP class structure that showcases different methods to:

• Get the current API version (so that we don’t have to hard code it in our code and always stay up-to-date)
• Find a product by category, product and keyword
• Get histogram data on a product category
• Get recommendations on possible alternatives to a user supplied search query (in case they spelled something wrong)

Here’s the code breakdown for that class.

If you quickly jump to the bottom of this code sample you will see a curl method. cURL will be the method that we use for making GET and POST requests to eBay API servers to obtain our the data that we are looking for. This is a standard method for making HTTP requests so we won’t cover that method any more than this.

The first thing that we need to do is to instantiate a new instance of this class by including the class file and instantiating a new class object:

require_once("finding.php");
$ebay = new ebay();

As soon as a new instance of the class is instantiated, the class constructor will be called, which in turn calls the getCurrentVersion method to obtain the most recently deployed version of the API (this keeps our applications all nicely up-to-date). getCurrentVersion will make a request to the finding API root endpoint, http://svcs.ebay.com/services/search/FindingService/v1, passing in the following data as query string parameters in the HTTP GET request:

• OPERATION-NAME: This will be getVersion for this API request
• SECURITY-APPNAME: Our application ID obtained when creating an application through our developer account from https://www.x.com/developers/ebay
• RESPONSE-DATA-FORMAT: The response format we want returned back – for our requests this will always be json

The method then makes an HTTP GET cURL request, obtains the response data, JSON decodes it into a proper PHP object, then extracts the version number and stores it in a class variable.

Now $ebay will provide us with access to the class methods that we need and the object will be instantiated with the most recent API version. Let’s see how each method is going to work.

Finding products

To search for eBay products, we would make requests much like the following to connect to the findProduct method:

$ebay->findProduct('findItemsByKeywords', 'Dresses Pants', 2);
$ebay->findProduct('findItemsByCategory', '63861', 2);
$ebay->findProduct('findItemsByProduct', '53039031');

The findProduct method is going to accept three parameters:

• search_type: What we want to search by, keyword, category or product id
• search_value: What we’re searching for, such as the keyword, category id or product id
• entries_per_page: How many results to return per call

When making the request, each request type will have a few custom parameters that will need to be set, denoted by the switch statement. These are:

• findItemsByCategory: We have to set the categoryID that we want to search for
• findItemsByProduct: We supply the productId.@type of ReferenceID and the productId, which is the search value supplied to the method
• findItemsByKeywords: We set the keywords parameter with what we are searching for

With those customer parameters set, there are a few more that will need to be included (which are generic for all requests):

• OPERATION-NAME: The request that we are making, either findItemsByCategory, findItemsByProduct or findItemsByKeywords
• SERVICE-VERSION: The current API version
• SECURITY-APPNAME: Our application ID
• RESPONSE-DATA-FORMAT: The format that we want back, in our case json
• REST-PAYLOAD: Stating that we are making a REST request and expecting a REST payload
• paginationInput.entriesPerPage: The number of results we want returned

We then make a cURL HTTP GET request to the API endpoint, with that data, and JSON decode the results.

Obtaining histogram data on a category

Besides finding products, let’s say that you want to get information about a particular category and/or fetch aspect histogram information about it. This is where you would use the getHistograms method, supplying a category ID as the only input, much like the following:

$ebay->getHistograms('63861');

Behind the scenes we’re making another request to the finding API and JSON decoding the resulting result set. At this point you will be able to see that a lot of the HTTP GET parameters that we have been supplying are fairly similar and standard for the request, and this request is no different. For the histogram data request we will be setting the following request parameters:

• OPERATION-NAME: The operation that we’re running, which is getHistograms in this case
• SERVICE-VERSION: The current API version
• SECURITY-APPNAME: Our application ID
• RESPONSE-DATA-FORMAT: The data format of the response – json
• REST-PAYLOAD: We are expecting a REST payload response
• categoryId: The category ID that we want data for

Getting keyword recommendations based on user input

Last but not least, we have to take into account that if you have some product search functionality, sometimes your users won’t spell so well. That’s where we would make a call to getKeywordRecommendations, passing in the word that we are searching for as the single parameter, much like the following:

$ebay->getKeywordRecommendations('acordian');

What this is going to return back to us is a list of suggestions (if any) for alternative ways of spelling the potentially misspelled word. Within the HTTP GET request we will be passing the following parameters:

• OPERATION-NAME: The operation that we’re running, which is getSearchKeywordsRecommendation in this case
• SERVICE-VERSION: The current API version
• SECURITY-APPNAME: Our application ID
• RESPONSE-DATA-FORMAT: The data format of the response – json
• REST-PAYLOAD: We are expecting a REST payload response
• keywords: The keywords that we want recommendations for

Get the code

If you would like to start working with this code and see the full examples for how to start finding products and getting recommendations, you can watch or fork the samples on Github at https://github.com/jcleblanc/commerce-applications/tree/master/ebay-samples/finding.

Jonathan LeBlanc
Twitter: @jcleblanc