Etsy Scraper

Search Etsy by keyword and get back listing title, price, discount, currency, shop, rating, review count, image and listing URL as clean rows. Filter by price range, digital downloads, sale badges and free shipping, and drop the promoted listings Etsy mixes into every page.

Give it a search term, the way a buyer would.

{
  "queries": ["leather bag", "leather backpack"],
  "category": "bags-and-purses",
  "max_results": 240,
  "min_price": 50,
  "max_price": 200,
  "include_ads": false
}

What you get

Field	What it is
listing_id	Etsy's own id. Stable, use it to join runs together
name	Listing title
url	Listing page
shop, shop_url, shop_id	The seller
price	Price as a number, in the currency your country selects
original_price	Price before the discount, when the listing shows one
discount_percent	The discount printed on the listing, as a whole number
currency_symbol	The symbol shown next to the price
rating, review_count	Shop rating out of 5 and the reviews behind it
is_ad	True when Etsy served this listing as a paid placement
free_shipping	True when the listing shows a free-shipping badge
digital_download	True when the listing is an instant download
etsys_pick	True when Etsy badges the listing as one of its picks
image	Listing image
query	Which of your search terms found this listing
position	Row position in the run

A note on shop: Etsy publishes the seller as schema.org brand. Calling that "brand" in the output would imply a manufacturer, which is wrong for a marketplace where the seller is the maker. It comes back as shop.

A note on ratings: a listing card often carries no rating. Those come back null rather than zero, because "not published" and "rated zero" are different facts and a zero would poison any average you compute.

A note on is_ad: roughly half of every Etsy search page is paid placement. Most tools hand you those rows silently. This one tags them, and include_ads: false removes them, so you can tell a ranking from an ad buy.

About half the page is advertising

On a typical leather bag search page, 6 of the 12 listings are "Ad from shop X". If you are measuring where a product ranks, or building a competitor price index, those six rows are noise that moves with somebody's ad budget rather than with the market. Set include_ads: false and the run returns organic listings only. The rowsDroppedByFilters count in the run summary tells you how many went.

Every filter here does something. Two that you might expect are missing

Filters were checked one at a time against an unfiltered baseline, and only the ones that actually changed the results are offered:

Filter	What we saw
min_price / max_price	A minimum of 200 returned prices from 204.75 up; a maximum of 25 returned nothing above 24.79. Unfiltered, the same search spans 12.24 to 230.00
digital_only	12 of 12 rows carried a download badge, against 0 of 12 with it off
country	A UK run returned every price in GBP, a US run in USD
on_sale_only	Applied to the rows after they are read, from the discount badge each listing prints. Every kept row proves itself through discount_percent
free_shipping_only	Applied the same way, from the free-shipping badge. Every kept row proves itself through free_shipping
include_ads	Applied from the "Ad from shop" label Etsy puts on the card

There is no sort option, and that is deliberate. Etsy will not serve a sorted search to this Actor: every sorted request comes back refused, including the "most relevant" default that should change nothing. Unsorted requests interleaved with them in the same minutes came back fine every time. Shipping a sort control that silently did nothing would be worse than not having one, so there isn't one. Sort the dataset yourself after the run.

There is no handmade or vintage filter either. Etsy accepts those as URL parameters and then returns the same listings at the same prices whichever value you send, and the listing cards carry no handmade badge to filter on afterwards. There is nothing honest to build there.

How much comes back

Etsy's search grid carries 12 listings per page. max_results is the total across all your search terms and max_pages caps how deep each term goes, so 240 results from two terms is 10 pages each. Pages are distinct: page 1, 2, 3 and 5 of the same search return different listings.

retries exists because Etsy refuses a small and fairly constant share of requests no matter how slowly you go, and a refusal clears on the next attempt. If you see fetch_failed, raise retries rather than concluding the site has closed.

Browsing a category instead of searching

Leave queries empty and set category_url to an Etsy category such as https://www.etsy.com/c/jewelry. Category pages publish their listings as structured data, so a category run returns around 60 rows per page rather than 12, and adds an availability field.

Shop pages (/shop/<name>) and individual listing pages (/listing/<id>) are refused up front with a message saying why, rather than spending your retries discovering it. The search grid already carries the price, shop, rating and discount that a listing page would give you.

Reading the run summary

Every run writes a summary record:

• listingsReturned, rowsBeforeFilters, rowsDroppedByFilters — what the filters cost you
• pagesFetched, rowsPerPage
• withPrice, withShop, withRating, uniqueShops — coverage, so you can see at a glance whether a field is thin before you build on it
• adRows, discountedRows
• exitCountry — which country priced the run

If a run returns nothing, the summary still carries rowsBeforeFilters, so you can tell "the search found nothing" apart from "your filters removed everything".

Free plan

Free Apify accounts get 10 results per run. Paid plans are uncapped. On a free run the Actor stops after one page instead of paging through listings it is not allowed to deliver.