Shopee Scraper

Collect public Shopee product listings by keyword, search URL, or numeric shop ID. The actor is intended to export product prices, images, sales counts, ratings, and seller indicators as structured records.

Validation status: the current public product endpoints returned HTTP 403 in the live golden check. That run produced zero records. This actor is not ready for publication or production use until a repeat golden check returns real products. Its output contract below describes the code path, not a verified production dataset.

What data can you extract from Shopee?

Each successful record is one product. Product and shop identifiers together form the deduplication key. A value can be empty when a listing does not expose it. Prices are converted from the listing endpoint's hundred-thousandth currency units into the market's major currency unit. The current implementation does not request product detail pages, so it cannot promise descriptions, specifications, variant stock, or vouchers.

Field	Description	Example or format
itemId	Numeric product identifier	integer
shopId	Numeric shop identifier	integer
url	Direct product link in the selected market	product URL
name	Listing title	text
image	Main product image	image URL
images	Other image URLs exposed by the listing	array of URLs
price	Current listing price	local currency number
priceMin	Lowest listed variant price	local currency number
priceMax	Highest listed variant price	local currency number
priceBeforeDiscount	Former displayed price	local currency number
discount	Discount label returned by the listing	text
currency	Currency for the selected market	TWD, SGD, or another listed code
soldMonthly	Recent sales count supplied by the listing	integer
historicalSold	Historical sales count supplied by the listing	integer
stock	Listing stock if exposed	integer
rating	Average product rating	number
ratingCount	Number of ratings	integer
likedCount	Number of likes	integer
shopName	Public shop name when supplied	text
shopLocation	Public shop location	text
isOfficialShop	Official shop indicator	boolean
isPreferredSeller	Preferred seller indicator	boolean
categoryId	Listing category identifier	integer
brand	Brand label when supplied	text
hasVideo	Whether video metadata is present	boolean
scrapedAt	Record collection time	ISO 8601 timestamp

The fields are deliberately flat. Product images are full URLs, while product and shop IDs remain separate so a downstream workflow can join records from multiple searches. An empty priceBeforeDiscount does not mean a discount exists but was missed; a listing may simply have no former price. An empty shopName means that name was absent from the listing response and should not be filled by guessing from a URL.

How to scrape Shopee

1. Enter one or more product keywords in searchTerms, or provide a supported search URL or numeric shop ID.
2. Choose the market. The default is Taiwan. Use terms in the market's language where possible.
3. Set a maximum product count and, if useful, a sort order or price and rating filters.
4. Run the actor and inspect its status. A blocked listing request fails visibly. A successful run can then be exported from its dataset.

The actor combines results from every supplied keyword and shop source. It removes duplicate products using the pair of shop and item identifiers. maxItems is a run-wide cap, not a cap per keyword. If the first keyword fills the cap, later keywords are not requested. To compare the same number of records from each keyword, run each keyword separately.

Input

Parameter	Type	Default	Description
searchTerms	string array	empty	Product keywords.
startUrls	URL list	empty	Search pages with a keyword query parameter or numeric /shop/ pages.
shopId	integer	empty	Numeric shop catalog ID.
region	string	TW	TW, SG, ID, MY, PH, TH, VN, or BR.
maxItems	integer	100	Maximum unique products across the run, up to 5,000.
sort	string	relevance	Relevance, newest, ascending price, descending price, or best selling.
priceMin	number	empty	Minimum current price in local currency.
priceMax	number	empty	Maximum current price in local currency.
minRating	number	empty	Minimum average star rating.
minSold	integer	empty	Minimum historical sales count.
discountedOnly	boolean	false	Keep records with a discount label.
officialShopOnly	boolean	false	Keep official shop listings.
preferredSellerOnly	boolean	false	Keep preferred seller listings.
withVideoOnly	boolean	false	Keep listings containing video metadata.
proxyConfiguration	object	enabled	Connection settings.

At least one of searchTerms, startUrls, and shopId is required. For a URL input, the hostname must match the selected region. A search URL needs a keyword query parameter. A shop URL needs a numeric ID in /shop/<id>. Product detail URLs and shop vanity names are outside the accepted URL format. Invalid sources fail before the first product request.

The golden input is:

{
  "searchTerms": ["手機殼"],
  "region": "TW",
  "maxItems": 40,
  "sort": "relevance"
}

That check requires at least 30 results and requires IDs, URLs, names, currency, and strong price and image coverage. Its latest run returned zero products because the listing endpoint denied the request.

Output example

There is no verified product record to show. The golden run returned zero records, so publishing an invented example here would misrepresent the available data. Once a golden run succeeds, replace this section with one actual dataset item and confirm the field fill rates against that item set.

Use cases

• Track public listing prices for a defined set of product keywords over time.
• Compare the public assortment of several numeric shop catalogs.
• Monitor ratings and recent sales indicators in a market segment.
• Export public product links and images for catalog review.
• Find discounted listings within a price range.
• Compare visible official shop and preferred seller indicators.

These uses depend on obtaining records. The current HTTP 403 response prevents the actor from serving them. A scheduled workflow should treat a failed run as missing data, never as evidence that products disappeared from the market.

How much does it cost to scrape Shopee?

The current build has not passed validation, so there is no reliable result-based cost or throughput measurement. The run attempted its first page and returned zero billable product records. Connection resources can still be consumed during failed attempts. Do not estimate a 1,000-product campaign from this failed run. Once access is restored, measure a successful 100-product run, then use the configured per-result price to estimate 1,000 and 5,000 products. For example, at a configured price of P per 1,000 results, 100 results would be 0.1 × P, 1,000 would be P, and 5,000 would be 5 × P, before any account-specific limits.

Tips for best results

Use specific search terms in the language commonly used by sellers in the selected market. The search endpoint paginates in groups of 60; this actor requests at most 30 pages for each source. A broad keyword can therefore expose only the beginning of the site's ranked result set. Add narrower terms to reach different result groups, and use the deduplication behavior to combine overlapping searches safely.

Choose a sort order that matches the question being asked. Relevance is appropriate for discovering products, newest for recent listings, ascending price for inexpensive offers, and best selling for high-volume listings. Sort order changes the records exposed by the site; it does not guarantee that every matching product can be reached through pagination. Price, rating, sales, and seller filters are applied to returned listing data. A strict local filter may leave fewer than maxItems records even when the site has more matching products.

Keep market and URL host consistent. A Taiwan search URL belongs with TW; a Singapore search URL belongs with SG. The actor constructs product links and image URLs for the chosen market. Product prices use that market's local currency, so do not compare raw price numbers across markets without a separate currency conversion step.

Limits

The principal limit is current access: public product search and shop listing endpoints returned HTTP 403 during research and the live golden run. The browser search page reached a traffic verification error. Changing sort parameters, normal request headers, proxy exit, and an app-style request did not produce product records. Public category and suggestion endpoints responded, but they do not contain the product listing fields needed here.

The listing endpoint is separate from product detail pages. Even after search access is restored, this implementation will not provide full descriptions, specifications, stock by variant, promotional voucher terms, or detailed shipping estimates. The table above is the implemented output contract. Some listing fields can be absent by product or market, and the actor represents them as empty values rather than inferred facts.

Pagination stops after 30 pages per keyword or shop. Results are deduplicated, so the final count can be smaller than the number of rows returned by the site. No login credentials are requested. If the site changes its response shape or access controls, the run can fail or produce fewer records and should be revalidated before use.

Automation

A consumer can pass the input object to a scheduled run, read the dataset after success, and compare the latest records with a prior snapshot. It should check the run status and expected row count before replacing a previous snapshot. A zero-row or failed run must remain visible as an ingestion failure. Once the golden check passes, the dataset can feed spreadsheets, internal price reports, and alerting workflows.

FAQ

Can I collect products by keyword and by shop in one run?

Yes. Supply search terms and a numeric shop ID together. Results are combined, and duplicate shop/item pairs are retained only once. The maximum count applies to the combined result set.

Can I paste a product URL?

No. The URL input accepts search pages with a keyword query and shop pages with numeric IDs. This actor collects listings rather than product detail pages.

Why is a field empty?

The listing response may not supply it for that product or market. Seller names, stock, brand, and former prices are examples of fields that can vary. Empty values should be treated as unknown, not as zero.

Does the actor need login credentials?

No credentials are accepted. It requests public listing data. At present, anonymous product requests are blocked even though some public metadata endpoints work.

How fast is a run?

No successful product run has been measured. The latest golden run failed on its first product page, so a speed estimate would be misleading.

Can results be exported to a spreadsheet?

After a successful run, the flat dataset can be exported in spreadsheet-compatible formats. No successful dataset exists yet for this build.

Is public product collection always permitted?

Only collect public data in a way that complies with the site's terms and applicable law. Avoid using the data to identify or profile people. This actor is scoped to product listings and public shop indicators.

Integrations

Once the actor passes validation, its default dataset can be consumed through an API or scheduled export and connected to workflow systems. Check run success and record count before sending data onward. A failed collection should trigger an alert rather than overwrite a report with an empty table.

Support

Open an issue describing the market, input, run status, and endpoint error. Include the count and field fill rates from a recent validation run when available.