A modern Ruby gem for the eBay REST APIs. Supports the Browse API, Marketplace Insights API, and Taxonomy API with OAuth 2.0 authentication.
Deprecation Notice: The eBay Finding API has been shut down. All
Ebay::Findingmethods now emit deprecation warnings and will be removed in v1.0.0. See Migration Guide below.
Add this line to your application's Gemfile:
gem 'ebay-api-ruby'And then execute:
bundle installOr install it yourself:
gem install ebay-api-rubyrequire 'ebay'
Ebay.configure do |config|
config.client_id = ENV['EBAY_CLIENT_ID']
config.client_secret = ENV['EBAY_CLIENT_SECRET']
config.marketplace_id = 'EBAY_US' # Default
config.timeout = 30 # Default
endEbay.configure do |config|
config.client_id = ENV['EBAY_SANDBOX_CLIENT_ID']
config.client_secret = ENV['EBAY_SANDBOX_CLIENT_SECRET']
config.sandbox!
endSearch for items, get item details, and search by image.
browse = Ebay::Browse.new
# Search items
results = browse.search(q: "vintage rolex", limit: 10)
results['itemSummaries'].each do |item|
puts "#{item['title']} - #{item['price']['value']} #{item['price']['currency']}"
end
# Get a specific item
item = browse.get_item("v1|123456789|0")
# Get items by group
items = browse.get_items_by_item_group("group123")
# Search by category (no keywords required)
results = browse.search_by_category("9355", limit: 10)
# Search by image
results = browse.search_by_image(Base64.encode64(File.read("watch.jpg")))Search sold/completed items for price history and market data.
insights = Ebay::MarketplaceInsights.new
# Search sold items
sold = insights.search(q: "pokemon base set charizard")
sold['itemSales'].each do |item|
puts "#{item['title']} - sold for #{item['lastSoldPrice']['value']}"
end
# With filters
sold = insights.search(q: "vintage rolex", category_ids: "31387", limit: 20)The Finding API has been shut down by eBay. All methods emit deprecation warnings. Use Browse and Marketplace Insights APIs instead. See Migration Guide.
Get category trees and browse category hierarchies.
taxonomy = Ebay::Taxonomy.new
# Get default category tree ID for a marketplace
tree_info = taxonomy.get_default_category_tree_id("EBAY_US")
tree_id = tree_info['categoryTreeId']
# Get the full category tree
tree = taxonomy.get_category_tree(tree_id)
# Get a subtree
subtree = taxonomy.get_category_subtree(tree_id, "9355")The gem handles OAuth 2.0 Client Credentials authentication automatically. Tokens are cached and refreshed when expired.
client = Ebay.client
# Manual authentication (usually not needed)
client.authenticate!
# Direct API calls
result = client.get("/buy/browse/v1/item_summary/search", q: "test")
result = client.post("/some/endpoint", { data: "value" })begin
browse.search(q: "test")
rescue Ebay::AuthenticationError => e
puts "Auth failed: #{e.message}"
rescue Ebay::NotFoundError => e
puts "Not found: #{e.message} (#{e.status_code})"
rescue Ebay::RateLimitError => e
puts "Rate limited. Retry after: #{e.retry_after}"
rescue Ebay::ValidationError => e
puts "Validation error: #{e.errors}"
rescue Ebay::APIError => e
puts "API error: #{e.message} (#{e.status_code})"
rescue Ebay::ConfigurationError => e
puts "Config error: #{e.message}"
endThe eBay Finding API has been shut down. Here's how to migrate to the replacement APIs:
| Finding (old) | Replacement (new) |
|---|---|
finding.find_items_by_keywords("query") |
browse.search(q: "query") |
finding.find_completed_items("query") |
insights.search(q: "query") |
finding.find_items_by_category("9355") |
browse.search_by_category("9355") |
finding.find_items_advanced(keywords: "q", categoryId: "9355") |
browse.search(q: "q", category_ids: "9355") |
Key differences:
- Auth: No more
app_id— all APIs use OAuth 2.0 (client_id+client_secret) - Response format: Clean REST JSON instead of the old nested XML-style format
- Filters: Browse API uses a
filterparameter (e.g.,filter: "price:[10..50],priceCurrency:USD") instead of Finding'sitemFiltersyntax
git clone https://github.com/esouza/ebay-api-ruby.git
cd ebay-api-ruby
bundle install
bundle exec rspecBug reports and pull requests are welcome on GitHub at https://github.com/esouza/ebay-api-ruby. See CONTRIBUTING.md.
The gem is available as open source under the terms of the MIT License.
