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:
With that said, let’s take a look at a simplified PHP class structure that showcases different methods to:
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:
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.
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:
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:
With those customer parameters set, there are a few more that will need to be included (which are generic for all requests):
We then make a cURL HTTP GET request to the API endpoint, with that data, and JSON decode the results.
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:
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:
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:
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:
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.