search_ebay: Search ebay
In gsimchoni/ebayr: R wrapper to the ebay Finding API

Description Usage Arguments Details Value References Examples

The primary ebayr function which allows you to search ebay using keywords, using one or more categories, or both. The function uses the "ebay Finding API" and the "findItemsAdvanced" call.

search_ebay(keywords = NULL, site = c("US", "UK", "DE", "AU"),
  categoryName = NULL, aspectFilter = NULL, nResults = 10,
  sortOrder = c("BestMatch", "EndTimeSoonest", "PricePlusShippingHighest",
  "PricePlusShippingLowest", "StartTimeNewest"), condition = c("All", "New",
  "Used", "Unspecified"), listingType = c("All", "FixedPrice", "Auction",
  "AuctionWithBIN"), priceRange = c(0, Inf), quantityRange = c(1, Inf),
  topRatedSellerOnly = FALSE, hideDuplicateItems = TRUE,
  freeShippingOnly = FALSE, sellerFeedbackRange = c(0, Inf),
  ebayToken = getEbayToken(), categoryId = NULL, returnAll = FALSE,
  verbose = TRUE)

`keywords`	Specify one or more words to use in a search query for finding items on eBay. By default, queries search item titles only.
`site`	The ebay site to search, a.k.a GLOBAL-ID. Currently only US, UK, DE and AU are supported. Defaults to US.
`categoryName`	Name of the ebay category or categories, if known. Unused if the `categoryId` is specified. Defaults to searching all categories but see details.
`aspectFilter`	List of name-value aspect to limit the query, e.g. `list(Color = "Black")`. See details.
`nResults`	Number of items requested, defaults to 10. The maximum allowed by ebay is 10000 (max. 100 pages x max 100 items per page, where each page is a separate request)
`sortOrder`	The order by which results are sorted. Defaults to "BestMatch", the site's default.
`condition`	Condition of item requested, e.g. "New". Defaults to "All".
`listingType`	Type of item requested, e.g. "Auction". Defaults to "All", see details.
`priceRange`	An integer vector of length 2 specifying the minimum and maximum item price requested, in the site's currency. Defaults to `c(0, Inf)`.
`quantityRange`	An integer vector of length 2 specifying the minimum and maximum item quantity requested. Defaults to `c(1, Inf)`.
`topRatedSellerOnly`	A boolean indicating whether only "Top Rated Sellers" are requested. Defaults to `FALSE`.
`hideDuplicateItems`	A boolean indicating whether to force return only distinct items. Defaults to `TRUE`. See details on why this is necessary.
`freeShippingOnly`	A boolean indicating whether only items with Free Shipping are requested. Defaults to `FALSE`.
`sellerFeedbackRange`	An integer vector of length 2 specifying the minimum and maximum seller feedback score requested. Defaults to `c(0, Inf)`.
`ebayToken`	The ebay AppID you got at https://go.developer.ebay.com. Default is to look for it with `Sys.getenv()`
`categoryId`	ID of the ebay category or categories, if known. Defaults to searching all categories but see details.
`returnAll`	A boolean indicating whether to return all API response parameters (for the last page) (`TRUE`) or just the items tibble (`FALSE`). Defaults to `FALSE`.
`verbose`	A boolean indicating whether to print to console the page progress which might be useful if `nResults` is very large. Defaults to `TRUE`.

The search_ebay function wraps a GET request to the ebay Finding API, using the httr package. Currently only the "findItemsAdvanced" call is supported, which means you can search for active items (i.e. still live on site) by keywords, by category or both.

In order to use this function you must either supply it with a valid "AppID" from https://go.developer.ebay.com via the ebayToken parameter, or register it to last for your entire R session with setEbayToken. For more details see README and blog post in References. Please note the API license ebay sets when signing up for a token as well as a daily rate limit of 5,000 requests.

keywords: For rules regarding keywords, see here categoryName: in general the API does not accept category names which are not unique (e.g. Digital Cameras), but only one or more category IDs. If more than a single categoryID belongs to each of the names specified, the function will warn you this happened but will continue regardless (up to a maximum of 3 categories allowed by the API). If no category is found whose name matches the input exactly, the function will suggest a few similar ones, try and pick one. Where to find the category name or ID?

through the ebay site (in an item's page, in the URL)
through previous results in the items tibble
or you might not need it, as the ebay search is quite good (e.g. shouldn't get results for "Nikon DSLR" in "Women's Handbags")

aspectFilter: this parameter allows you to further refine your results, e.g. specifying aspectFilter = list("Storage Capacity" = "64GB") when searching for "iPhone X", will only return iPhones with the specified Storage Capacity. Naturally these possible name-values differ from category to category and currently the best place to look for them is by looking at the left side bar in the search results page. Only one "value" per "name" is supported in this function.

listingType:

FixedPrice: no auction activity on this item, either from a private seller or from a store ("StoreInventory"). Most items on ebay.
Auction: an auction item, most importantly this means that the price you see is not finite!
AuctionWithBIN: these are auction items which also have a "Buy It Now" option, which means you can bypass the auction and just pay a certain price

hideDuplicateItems: this parameter defaults to TRUE because there's a good chance that without it you'll get quite a few duplicate items. One of the reasons might be "Multi Variation" items, when a seller uses a single item to list different versions of the same "thing", e.g. a shirt which comes in various colors. Without specifying hideDuplicateItems = TRUE each of these shirts might return as a separate item, with its own price. There are other reasons, and this could get confusing. For example when comparing prices you might want to consider removing all items in the items tibble which have TRUE in the isMultiVariationListing column.

Details regrding the items tibble (these are the tibble's columns):

itemId: ebay's unique item ID for each item
title: item's title as it appears on site
categoryId: item's primary category ID, note that an item can have a secondary category, not returned here
categoryName: category's name
viewItemURL: item's URL on ebay
location: a string specifying the item's location, e.g. "Melbourne, Australia"
shippingType: free or some other values, see API Reference
shipToLocations: Worldwide or other values, see API Reference
isMultiVariationListing: see details on the hideDuplicateItems parameter
conditionId: ebay's ID for a condition, e.g. "1000" for "New"
conditionName: name of condition, e.g. "New", "Used"
listingType: see details on the listingType parameter
startTime: the time the item successfully uploaded to site
endTime: the time the item is scheduled to end, this could be sooner if it sells
watchCount: no. of users watching the item in their watchlist, could be NA for some reason
price: current price of the item in the site's currency, notice what this means for auction items
currency: the price currency, e.g. "AUD" for Australian Dollars

If returnAll == TRUE, a EbayResponse R6 Class instance containing:

`url`	The URL that was formed for the API GET request
`queryList`	The list of name-value pairs attached to the GET request
`site`	The site requested
`nResultsRequested`	Number of results requested
`nResultsAvailable`	Number of results in potential, on site
`nResultsFinal`	Final number of results found (could be quite lower than `nResultsRequested`, not only because `nResultsAvailable` is less requested. If `hideDuplicateItems == TRUE` (default) many duplicates might have been removed.)
`timestamp`	The time of the last page request
`itemSearchURL`	The URL to view the results for the last page on ebay - this comes from ebay and is not accurate
`page`	The number of the last page
`totalPages`	No. of pages for this request
`items`	The tibble holding the items data, see details.

Otherwise only the items tibble will be returned (the default).

A blog post describing the package with more examples: http://giorasimchoni.com/2017/12/19/2017-12-19-e-is-for-elephant-the-ebayr-package/ The ebay Finding API documentation: https://developer.ebay.com/Devzone/finding/Concepts/FindingAPIGuide.html

search_ebay("iPhone X")
search_ebay("Nikon DSLR", categoryName = "Digital Cameras",
  aspectFilter = list(Model = "Nikon D5500"), condition = "New",
  listingType = "FixedPrice")