In the previous article we saw how to perform the preliminary steps to prepare our working environment, create an Ebay developer and a sandbox account and generate the keys and credentials needed to execute API calls. In this new chapter we will create our first request and perform our first call focusing on the “Finding API”
In this tutorial you will learn:
- What are the possible “Finding API” calls;
- What are the parameters you can use to customize you call;
- How to build a request with the python SDK;
- How to perform an API call;
Software Requirements and Conventions Used
| Category | Requirements, Conventions or Software Version Used |
|---|---|
| System | Operating system agnostic. |
| Software | git and python3 |
| Other | Knowledge of the python programming language and of the basic object oriented concepts. |
| Conventions | # – requires given linux commands to be executed with root privileges either directly as a root user or by use of sudo command$ – requires given linux commands to be executed as a regular non-privileged user |
The Finding API
The Finding API is the first one we explore in this series of articles about programmatically interact with Ebay by using python and the Ebay python SDK. This API provides calls that can be very useful both for buyers and sellers and provides us access to the Ebay platform search capabilities, providing a faster way to retrieve and manipulate data compared to web scraping techniques.
The Finding API calls
The following are, in my opinion, the most relevant calls provided by the Finding API:
- findItemsAdvanced – Let us perform complex queries and apply filters;
- findItemsByCategory – Let us find articles belonging to a specific category;
- findItemsByKeywords – With this call we can find items based on keywords;
- findItemsByProduct – With this call we can find items based on identifiers like ISBN, EAN, UPC and ePID;
You can find the complete list of available calls for the Finding API in the dedicated page.
In this tutorial, however we will focus on the findItemsByKeywords call.
Before we begin
In the previous article of this series we set up our working environment, therefore from now on I will assume that you have correctly install the Ebay python SDK and created you API keys. Since we are working with the Finding API, we can work directly on the production site.
Let’s begin, then. As a first thing we create a directory as the base of our project; we will (surprisingly) call it “ebay”:
$ mkdir ebay
Inside this directory, we need store our credentials in the ebay.yaml file, as we discussed in the previous article. You can find a template of this file inside the root of the github repository we cloned. Here is the content of my ebay.yaml file, in which I have already entered my credentials:
Finding API, is the App ID for our production environment.Our first API call
By default Ebay accepts API request and provide in the form of xml structures: what makes us possible to interact with those elements in an object oriented way is the python SDK. Now that we have our credentials in place, we can begin to create our first API request. Create a new file an call it findbykeywords.py, inside of it the first thing we need to do is to import the needed modules:
#!/usr/bin/env python3
from ebaysdk.finding import Connection
The next thing to do is to initialize an instance of the Connection class, here is how we do it:
api = Connection(config_file='ebay.yaml', siteid="EBAY-US")
We passed some parameters to the constructor of the Connection class: config_file, and siteid. The first one is needed to specify the path to the file containing our credentials: since by default its value is the same of the one we provided, we could have omitted it. The second arguments it’s needed to specify the Ebay country site the request should be pointed to: "EBAY-US" is the default. If I wanted to perform my search on the Italian site, for example, I would have used "EBAY-IT" instead. Many other parameters can be passed to tweak the default configuration, but for know our setup is sufficient. Let’s proceed further.
We initialized our instance of the Connection class, now we need to build a request, which will be included in the API call. Thanks to the python SDK, we can represent a request with a dictionary, specifying its parameters with key-value pairs:
request = {
'keywords': 'lord of the rings',
}
The above is the minimal possible request for the findItemsByKeywords call: we just specified the keywords to search. This is possible because 'keywords' is the only required parameter for this call.
Depending on the call we want to perform we can use many other parameters to refine our request. To know exactly all the available request parameters for a specific call you can consult the pretty detailed Ebay documentation for it.
Restricting our search with a filter
We can specify a list of filters inside our request, so that the number of returned results will be reduced. Inside the request, the itemFilter key is associated with an array containing all the filters, each of them in the form of a dictionary, where the name key is associated with a string representing the filter name, and the value one is associated with the actual value that should be use for the filter. Let’s see an example. Say we want to add filter to our request, in order to restrict our search only to “new” items:
request = {
'keywords': 'lord of the rings',
'itemFilter': [
{'name': 'Condition', 'value': 'New'}
]
}
In the example above we used the condition filter, but many others are available. For example, the ExcludeSeller filter is useful to exclude specific sellers from the results, while the FreeShippingOnly one to restrict the search only to items sold with free shipping. The list of filters and their possible values is really long: again, you can find all of them consulting the official documentation.
Paginating the results
Another very useful parameter we can add to our request is paginationInput. By using it we can specify a desired pagination format. Inside the request, the paginationInput key is associated with a dictionary, itself containing two keys: entriesPerPage and pageNumber.
With the first one we can specify how many results we want to receive “per page”: no more than 100 results per page are supported (this is also the default value), while the minimum is 1. With the second element, pageNumber, we can specify what page we want to receive in the results.
Say, for example that we wanted no more than 10 results per page and we were interested only in the first page, our request would become:
request = {
'keywords': 'lord of the rings',
'itemFilter': [
{'name': 'condition', 'value': 'new'}
],
'paginationInput': {
'entriesPerPage': 10,
'pageNumber': 1
}
}
Actually we could have omitted pageNumber, since its default value is always “1”.
Sorting the results
Another very useful parameter we can add to our request, is sortOrder. With this parameter we can use one of the available sorting criteria to better organize our results. Say for example we wanted to sort our results by price in ascending order, so to have the cheapest items included in the results first:
request = {
'keywords': 'lord of the rings',
'itemFilter': [
{'name': 'condition', 'value': 'new'}
],
'paginationInput': {
'entriesPerPage': 10,
'pageNumber': 1
},
'sortOrder': 'PricePlusShippingLowest'
}
In this case we used PricePlusShippingLowest as a sort order, so the items included in the results, will be sorted in ascending order by the result of the sum of their price and their shipping fee. Just like filters, the available sorting orders are too many to be reported here. Among the others we can use DistanceNearest or EndTimeSoonest to sort the results by distance in ascending order, or by closest endtime respectively. You can find all the possible sorting criteria by consulting this table.
Sending our request and getting the results
Now that we have finished creating our request we must actually send it to Ebay and get the results. To accomplish the first task, we use the execute method on our api object, specifying the name of the call we want to use as the first argument, and the dictionary representing our request as the second one. Here is what our script looks in its entirety at this point:
#!/usr/bin/env python3
from ebaysdk.finding import Connection
if __name__ == '__main__':
api = Connection(config_file='ebay.yaml', debug=True, siteid="EBAY-US")
request = {
'keywords': 'lord of the rings',
'itemFilter': [
{'name': 'condition', 'value': 'new'}
],
'paginationInput': {
'entriesPerPage': 10,
'pageNumber': 1
},
'sortOrder': 'PricePlusShippingLowest'
}
response = api.execute('findItemsByKeywords', request)
Our results will be returned, and we will reference it with the response variable. We now want to organize them, so that for each result we can have the title and price displayed onscreen in a nice format, we can add a simple loop to accomplish this result:
for item in response.reply.searchResult.item:
print(f"Title: {item.title}, Price: {item.sellingStatus.currentPrice.value}")
If we now try to launch the script, we obtain the following results:
Title: Lord of the Rings The One Ring Lotr Stainless Steel Fashion Women ManRing Sz12, Price: 0.01 Title: Lord of the Rings The One Ring Lotr Stainless Steel Fashion Men Women Ring Sz13, Price: 0.01 Title: Lord of the Rings The One Ring Lotr Stainless Steel Fashion Men Women Ring Size9, Price: 0.01 Title: Lord of the Rings The One Ring Lotr Stainless Steel Fashion Men Women Ring Sz13, Price: 0.01 Title: Lord of the Rings The One Ring Lotr Stainless Steel Fashion Men Women Ring Sz11, Price: 0.01 Title: Lord of the Rings The One Ring Lotr Stainless Steel Fashion Men Women Ring Size7, Price: 0.01 Title: Lord of the Rings The One Ring Lotr Stainless Steel Fashion Men Women Ring Sz12, Price: 0.01 Title: Lord of the Rings The One Ring Lotr Stainless Steel Fashion Men Women Ring Size9, Price: 0.01 Title: Lord of the Rings The One Ring Lotr Stainless Steel Fashion Men Women Ring Size8, Price: 0.01 Title: Lord of the Rings The One Ring Lotr Stainless Steel Fashion Men Women Ring Sz13, Price: 0.01
At this point you may ask: how can I know the exact structure of the results? It is a good question, and you can have an answer by checking the xml representation of the output of a call request you can in the ebay documentation dedicated to the specific call. You can find the one about findItemsByKeywords by following this link.
Conclusions
While in the previous article we talked about how to setup our working environment, obtain our API keys and install the python SDK, in this second part of our series of articles about Ebay APIs we approached the Finding API, and we built a simple request using the findItemsByKeywords call. We saw briefly how to add filters and specify a sorting order to our request and how to work with the returned results.
In the next article, among the other things, we will build our store and we will see how to use the Trading API to create and upload an item to it. In conclusion here is a recap of the official documentation we referenced in this article:
- Documentation about the
findItemsByKeywordscall - List of available request filters
- List of available sorting orders
- List of available calls for the
Finding API
Table of Content
