ebay-sold-listings-search

What it does

Translates a keyword and filter set into a sold-listings search across eight eBay sites, then returns paginated, structured records for confirmed sales, including itemId, url, title, endedAt, soldPrice, listingType, shipping, seller, and images. It targets only listings already displayed on screen and avoids bypassing authentication.

How it works

• Builds a sold-listings URL using the provided keyword and parameters via the URL builder script. Commands and parameters include: URL=$(python scripts/build-url.py '{keyword}' --ebaySite {ebaySite} --sortOrder {sortOrder} --categoryId {categoryId} --subcategoryId {subcategoryId} --itemLocation {itemLocation} --itemCondition {itemCondition} --minPrice {minPrice} --maxPrice {maxPrice} --includeCompletedListings {true|false} --ipg {60|120|240} --page {pageNumber}).
• Navigates to the URL and waits for results with wait --selector "li.s-card".
• Runs extract-page.py with --keyword to produce a JSON structure containing items, pagination, and metadata.
• Handles errors by inspecting the page for splash or error states and retrying as specified; on permanent failure, marks the keyword incomplete.
• Processes each item to produce per-item records containing fields such as itemId, url, title, condition, conditionId, endedAt, soldPrice, soldCurrency, listingType, isBestOfferAccepted, buyingFormat, bidCount, shippingPrice, shippingCurrency, shippingType, totalPrice, thumbnailUrl, fullResThumbnailUrl, sellerUsername, sellerPositivePercent, sellerFeedbackScore, sellerType, keyword, and scrapedAt.
• Supports pagination across pages while collecting until hasNextPage is false or a user-defined limit is reached, then deduplicates by itemId.

When to use it

Use when user explicitly queries ebay sold listings, ebay sold prices, ebay completed listings, or ebay comps, and you need a structured, paginated set of sold-records across multiple marketplaces.

What it can touch

• The skill touches browser pages and uses tool scripts for URL building and data extraction:
  • URL=$(python scripts/build-url.py '{keyword}' ...)
  • navigate "$URL"
  • wait --selector "li.s-card" ...
  • eval "$(python scripts/extract-page.py --keyword '{keyword}')"
• No direct file writes or external API calls are described beyond the provided scripts and browser-act workflow.

Caveats

• soldPrice for Best Offer Accepted listings reflects the listing price, not the actual accepted offer, when BOA is detected; this is a data-source limitation.
• eBay’s URL does not support a direct sold-date range; time-window scoping relies on sorting by endedRecently and stopping pagination.
• sellerType is labeled only on EU marketplaces (ebay.de, ebay.fr, ebay.it, ebay.es); null on other sites.
• The extractor may encounter anti-scrape or splash pages; its error handling advises re-navigation or switching to a stealth browser if blocked.