eBay

eBay listings and their sellers behind the same canonical commerce schema as Amazon, Walmart, Target and Google Shopping. Two endpoints: a deep keyword search across any of nineteen national marketplaces, and a full listing record that carries the seller's reputation alongside the item.

Base URL: /v1/ebay/...

Listings are keyed on the item id, the number in a listing URL. In ebay.com/itm/327256602116 the item id is 327256602116, and every search row carries one.

Quickstart

curl "https://www.socialcrawl.dev/v1/ebay/search?query=airpods%20pro&sort_by=price_low&condition=new" \
  -H "x-api-key: YOUR_API_KEY"

curl "https://www.socialcrawl.dev/v1/ebay/product?product_id=327256602116" \
  -H "x-api-key: YOUR_API_KEY"

Search

The filters map directly onto eBay's own refinements:

• sort_by: best_match (default), price_low, price_high, newly_listed, ending_soonest
• condition: new, refurbished, used
• buying_format: auction, buy_it_now, accepts_offers
• show_only: sold_items, completed_items, free_shipping, or a comma-joined pair such as sold_items,completed_items
• aspects: a category-specific item aspect from a previous response, such as Brand:Apple

Sold and completed listings

eBay's public sold search requires a signed-in browser session. This endpoint does not: you never pass an eBay login, cookie, or session. Call show_only=sold_items and read the realised sale on product.price.current and the sold date on product.ext.sold_at.

curl "https://www.socialcrawl.dev/v1/ebay/search?query=airpods%20pro&show_only=sold_items" \
  -H "x-api-key: YOUR_API_KEY"

completed_items returns every ended listing, including those that did not sell. Combine the two tokens when you want that full ended set with sold dates still stamped on the rows that sold. eBay itself only exposes about ninety days of sold history through search.

Listing detail

The seller block is the reason to call this rather than search. product.ext.seller_reputation carries lifetime feedback percentage and count, top-rated status, items sold, join date, and four detailed sub-ratings for description accuracy, shipping cost, shipping speed, and communication. When you are evaluating who is selling as much as what is being sold, this is the endpoint that answers it.

Marketplaces

country selects the national marketplace, and it sets the listing pool, the language and the currency together rather than just a display preference. US (ebay.com) is the default. GB, AU, CA, DE, FR, IT, ES, IE, AT, CH, NL, BE, PL, SG, MY, PH, HK and MX are the rest.

All endpoints

2 endpoints available.

Platform notes

Price filters are approximate. min_price and max_price are applied by eBay, not by us, and the boundary rows are not exact. Filter on product.price.current in the response if you need a hard bound.

image_urls is null on listing detail. eBay's detail response currently returns a corrupt image array, so the field nulls out rather than carrying a broken URL. Use the image on the matching search row, which is unaffected.

There is no category-browse endpoint. Unlike Target or Walmart, eBay's tree is not exposed here. Keyword search plus aspects refinement is the path from nothing to a set of item ids.

Auction listings are moving targets. A buying_format=auction row's price is the current bid, so a listing fetched twice legitimately reports two different numbers. Read sort_by=ending_soonest results as a snapshot rather than a stable set.

Paginate until a page comes back empty. eBay's own result total is an estimate that changes between pages, so it is not returned here. Search is page-paginated starting at page=1, and prices come back in the marketplace's own currency.

Next steps