Ebay Search Listing

eBay — Search & Category Listing Extraction

Input: any eBay search or category page URL → Output: paginated array of item cards (itemNumber, url, title, price, seller, image, etc.) plus pagination state (currentPage, nextPageUrl, hasNextPage, totalResultsApprox).

Language

All process output to user (progress updates, process notifications) follows the user's language.

Objective

Given any eBay search results URL (SRP) or category URL, extract the visible product cards on the current page with their key surface fields, and expose pagination state so a caller can loop pages until an item cap or the last page is reached.

Prerequisites

• Target page is already open in the browser: https://www.ebay.{tld}/sch/i.html?_nkw={keyword} (search) or https://www.ebay.{tld}/b/{category-slug}/{category-id}/bn_... (category), where {tld} is any eBay regional TLD (com, co.uk, de, fr, it, es, com.au, ca, co.jp, com.hk, in, ph, pl, nl, ie, at, be).
• No login is required for public listings. Extraction runs against whatever the anonymous browser session sees.

Pre-execution Checks

1. Tool Readiness

If browser-act has been confirmed available in the current session → skip this step.

Invoke browser-act via Skill tool to load usage. If installation or configuration issues arise, follow its guidance to resolve then retry.

Capability Components

This Skill's operational boundary = what the user can manually do in their browser. It only reads data already displayed to the user on the page, never bypassing authentication or access controls. Its role is equivalent to copy-pasting on the user's behalf — the data is already on screen, automation merely saves time. JS code is encapsulated in Python files under the scripts/ directory, invoked via eval "$(python scripts/xxx.py {params})". $(...) is bash syntax; it is recommended to use the bash tool for execution.

Below are all atomic capabilities discovered and verified during the exploration phase. Simply invoke them as needed — no need to read scripts/*.py source code or re-verify. Only inspect scripts when execution fails for troubleshooting.

DOM: extract item cards from the current search or category page

Precondition: navigate {search or category URL} → wait stable first.

Extract: eval "$(python scripts/extract-listing.py --max-items 0)"

Parameters:

• --max-items: Cap on cards returned from the current page. 0 (default) returns every card on the page. Use a positive integer when the caller only wants the top-N of the current page (does not affect pagination state).

Output example:

{
  "currentUrl": "https://www.ebay.com/sch/i.html?_nkw=headphones&LH_BIN=1",  // page URL as observed
  "hostname": "www.ebay.com",                       // regional domain of the current page
  "currentPage": 1,                                 // 1 when the URL has no _pgn param
  "nextPageUrl": "https://www.ebay.com/sch/i.html?_nkw=headphones&LH_BIN=1&_pgn=2",  // null when on last page
  "hasNextPage": true,                              // false = last page reached
  "totalResultsApprox": 250000,                     // parsed from the results-count heading; null if not shown
  "totalResultsRaw": "250,000+ results for headphones",  // original heading text
  "itemsOnPage": 60,                                // eBay default is 60 per page; can be overridden by _ipg URL param
  "returnedCount": 3,                               // number of items in the "items" array below (respects --max-items)
  "items": [
    {
      "itemNumber": "195486024424",                 // eBay listing id (also from data-listingid on the card)
      "url": "https://www.ebay.com/itm/195486024424",  // canonical item URL, query params stripped
      "title": "Plugfones Guardian OSHA Certified earplug with audio Work Headphones earbuds",
      "subtitle": "Brand New",                      // condition / seller-type badge; null when absent
      "caption": null,                              // e.g. "New Listing", "Sold Jul 7, 2026"; null when absent
      "price": 24.99,                               // parsed numeric price
      "priceWithCurrency": "$24.99",                // original price string
      "currency": "USD",                            // ISO code detected from price prefix
      "wasPrice": null,                             // original / strikethrough price if shown
      "wasPriceWithCurrency": null,
      "bids": null,                                 // auction bid count; null for BIN listings
      "shipping": "+$12.99 delivery",               // shipping-row text as displayed; null when absent
      "seller": "plugfones",                        // seller username
      "sellerRawText": "plugfones 99.7% positive (15.9K)",  // original seller badge text
      "sellerFeedbackCount": 159000,                // parsed from (15.9K); handles K suffix
      "sellerPositiveRating": 99.7,                 // percentage as float
      "reviewsCount": null,                         // product-review count when displayed on the card
      "starRating": null,                           // 0-5 star rating when displayed
      "image": "https://i.ebayimg.com/images/g/PbYAAOSwuHdjcqCX/s-l1600.webp"  // upgraded to s-l1600 for the largest available crop
    }
  ]
}

Error handling:

• When .srp-results > li.s-card matches zero elements, the script returns {"error": true, "message": "no item cards found ..."}. Root causes: the page navigated to an item detail (URL contains /itm/), an anti-bot interstitial is shown, or eBay changed the class prefix. Take a screenshot first, verify the URL is still an SRP or category page, then retry.
• When the browser is fingerprinted and eBay serves a captcha page, follow the standard captcha escalation (solve-captcha, headed handoff, remote-assist).

Pagination

URL Pagination: URL pattern ?_pgn={page} (append &_pgn=N to any search or category URL; page 1 = no param, or _pgn=1). eBay's default page size is 60 items; add &_ipg={size} (accepted values include 60, 120, 240) to change it. Next-page detection selector: a.pagination__next, exposed by the extractor as nextPageUrl / hasNextPage. Termination: hasNextPage === false, or the caller-supplied item cap is reached, or a page returns zero items.

Loop skeleton (bash pseudocode):

url="{startUrl}"
collected=0
maxItems={caller-cap}
while [ -n "$url" ]; do
  browser-act --session {name} navigate "$url"
  browser-act --session {name} wait stable
  page=$(browser-act --session {name} eval "$(python scripts/extract-listing.py --max-items 0)")
  # append page.items to output, respecting maxItems
  next=$(echo "$page" | jq -r '.nextPageUrl // empty')
  hasNext=$(echo "$page" | jq -r '.hasNextPage')
  [ "$hasNext" = "true" ] || break
  [ "$collected" -ge "$maxItems" ] && break
  url="$next"
done

Success Criteria

returnedCount >= 1 on any non-empty search / category page, and error field is absent. Card-level: itemNumber and url are non-null for every returned card (title is normally non-null but can be empty for restricted or ended listings — that is a page-side condition, not a scraper failure).