eBay

eBay listings and their sellers behind the same unified envelope and canonical commerce schema as Amazon, Walmart, Target and Google Shopping, so one parser handles all of them. 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/...

Getting started

Every endpoint is a GET with query parameters and an x-api-key header. Listings are identified by item id, the number in a listing URL — ebay.com/itm/327256602116 is item id 327256602116. Every row returned by search carries one.

# 1. Scan the marketplace, sixty listings per page
curl "https://www.socialcrawl.dev/v1/ebay/search?query=airpods%20pro&sort_by=price_low&condition=new" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"

# 2. One listing in full, including who is selling it
curl "https://www.socialcrawl.dev/v1/ebay/product?product_id=327256602116" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"

Both endpoints are 5 credits.

Search

GET /v1/ebay/search returns sixty listings per page — more rows per call than any other listing endpoint here — each with the item id, title, price, condition, image, seller handle, feedback score and units sold. That density is what makes eBay the cheapest marketplace on this API to scan at depth.

The filters map directly onto eBay's own refinements:

• sort_by — best_match (default), price_low, price_high, newly_listed, ending_soonest
• condition — new, opened_box, refurbished, used
• buying_format — auction, buy_it_now, accepts_offers
• min_price / max_price — a price band
• show_only — an eBay refinement token taken from a previous response, such as free_shipping or sold_items
• aspects — a category-specific item aspect from a previous response, such as Brand:Apple

show_only and aspects are the two you cannot guess: their valid values are category-specific and come back on the response you are refining, so run the broad search first and read the tokens off it.

Listing detail

GET /v1/ebay/product?product_id=… returns the listing in full — title, brand, price, condition, MPN and UPC, quantity available, and watcher count. What sets it apart from the other commerce platforms here is the seller block: feedback score, top-rated status, join date, and four detailed sub-ratings. 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 — not 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. Pass the same country on product that you used on search, because an item id resolves within its own marketplace.

Endpoints

2 endpoints available.

Read this before you build

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

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, not a stable set.

Notes

• All endpoints use GET with query parameters
• Authentication via the x-api-key header
• Responses follow the unified SocialCrawl schema, shared with the other commerce platforms
• Search is page-paginated starting at page=1
• Prices are returned in the marketplace's own currency