from __future__ import annotations import csv import html import re import tempfile from typing import Any, Dict, List, Optional, Tuple from urllib.parse import urlparse import gradio as gr from tool import COUNTRIES, MAX_BULK, MAX_SEARCH_PAGES, SCRAPE_DO_SIGNUP_URL, ScrapeDoEtsyTool # ZeroGPU hardware refuses to keep a Space alive unless it finds at least one # @spaces.GPU function at startup. This app is pure HTTP and never touches a GPU, # so the probe below exists only to satisfy that check. It is never called. try: import spaces @spaces.GPU(duration=1) def _zerogpu_probe() -> str: return "ok" except ImportError: pass COUNTRY_CHOICES = [(label, code) for label, code, _ in COUNTRIES] SORT_CHOICES = [ ("Most relevant", "relevance"), ("Newest", "newest"), ("Price: low to high", "price_low"), ("Price: high to low", "price_high"), ("Top customer reviews", "top_reviewed"), ] NO_TOKEN_MD = ( "### Paste your Scrape.do API token above\n\n" f"No token yet? [Create a free account]({SCRAPE_DO_SIGNUP_URL}) — " "1,000 free credits a month, no credit card. Each Etsy page costs 10 credits." ) # --------------------------------------------------------------------- helpers def _esc(value: Any) -> str: return html.escape("" if value is None else str(value), quote=True) def _safe_link(url: Any) -> str: url = str(url or "") return url if url.startswith(("http://", "https://")) else "" def _num(value: Any) -> Optional[float]: try: return float(str(value).replace(",", "")) except (TypeError, ValueError): return None def _fmt_int(value: Any) -> str: number = _num(value) return f"{int(number):,}" if number is not None else _esc(value) def _money(price: Any, currency: Any) -> str: number = _num(price) if number is None: return "" cur = str(currency or "") text = f"{number:,.2f}" if not cur: return text # ISO codes (USD) read better with a space, symbols ($) do not. return f"{cur} {text}" if cur.isalpha() else f"{cur}{text}" def _tool_or_none(token: str) -> Optional[ScrapeDoEtsyTool]: if not token or not token.strip(): return None return ScrapeDoEtsyTool(api_token=token.strip()) def _write_csv(rows: List[Dict[str, Any]], prefix: str) -> Optional[str]: if not rows: return None fieldnames: List[str] = [] for row in rows: for key in row: if key not in fieldnames: fieldnames.append(key) handle = tempfile.NamedTemporaryFile( mode="w", suffix=".csv", prefix=f"{prefix}-", delete=False, newline="", encoding="utf-8-sig", ) writer = csv.DictWriter(handle, fieldnames=fieldnames) writer.writeheader() for row in rows: writer.writerow({key: row.get(key, "") for key in fieldnames}) handle.close() return handle.name def _error_md(data: Dict[str, Any]) -> str: out = f"**That didn't go through.**\n\n{data.get('errorMessage') or 'Unknown error'}" if data.get("hint"): out += f"\n\n{data['hint']}" return out def _stars(rating: Any) -> str: value = _num(rating) if value is None: return "" full = max(0, min(5, int(round(value)))) return f'{"★" * full}{"★" * (5 - full)}' def _rating_line(rating: Any, count: Any) -> str: if _num(rating) is None: return '
No reviews yet
' count_html = f'({_fmt_int(count)})' if count not in (None, "") else "" return ( f'
{_num(rating):.1f}' f"{_stars(rating)}{count_html}
" ) def _button(label: str, href: str, primary: bool = False) -> str: if not href: return "" cls = "et-btn et-btn-primary" if primary else "et-btn" return f'{label}' def _img(src: Any, cls: str) -> str: link = _safe_link(src) if not link: return "" return ( f'' ) def _badge(text: str, kind: str = "") -> str: return f'{_esc(text)}' TAG_SVG = ( '' ) # ------------------------------------------------------------ search results def render_listings(listings: List[Dict[str, Any]]) -> str: if not listings: return '
No listings came back for this search.
' cards: List[str] = [] for item in listings: price = _money(item.get("price"), item.get("currency")) price_html = f'{_esc(price)}' if price else "" if item.get("original_price"): price_html += f'{_esc(_money(item["original_price"], item.get("currency")))}' if item.get("discount_percent"): price_html += f'{item["discount_percent"]:g}% off' badges = "" if item.get("is_ad"): badges += _badge("Ad", "et-badge-ad") if item.get("bestseller"): badges += _badge("Bestseller") if item.get("star_seller"): badges += _badge("Star Seller") if item.get("free_shipping"): badges += _badge("Free shipping", "et-badge-green") if item.get("only_left"): badges += _badge(f"Only {item['only_left']} left", "et-badge-warn") link = _safe_link(item.get("url")) name = _esc(item.get("name") or "Untitled listing") name_html = ( f'{name}' if link else f'{name}' ) cards.append( '
' f"{_img(item.get('image'), 'et-thumb')}" '
' f'
{_esc(item.get("position"))}
{name_html}' f'
{price_html}
' f"{_rating_line(item.get('rating'), item.get('review_count'))}" + (f'
{badges}
' if badges else "") + "
" ) return f'
{"".join(cards)}
' def _listing_rows(listings: List[Dict[str, Any]]) -> List[Dict[str, Any]]: return [ { "position": i.get("position"), "listing_id": i.get("listing_id"), "name": i.get("name"), "price": i.get("price"), "original_price": i.get("original_price"), "discount_percent": i.get("discount_percent"), "currency": i.get("currency"), "rating": i.get("rating"), "review_count": i.get("review_count"), "shop_id": i.get("shop_id"), "star_seller": i.get("star_seller"), "free_shipping": i.get("free_shipping"), "bestseller": i.get("bestseller"), "is_ad": i.get("is_ad"), "only_left": i.get("only_left"), "image": i.get("image"), "url": i.get("url"), } for i in listings ] # ------------------------------------------------------------- listing card def render_listing(listing: Dict[str, Any], reviews: List[Dict[str, Any]]) -> str: images = [src for src in (listing.get("images") or []) if _safe_link(src)] hero = _img(images[0], "et-hero-img") if images else "" thumbs = "".join(_img(src, "et-gal-img") for src in images[1:9]) price = _money(listing.get("price"), listing.get("currency")) if listing.get("price_high") and listing.get("price_high") != listing.get("price"): price += f" – {_money(listing['price_high'], listing.get('currency'))}" chips = "" if listing.get("category"): chips += f'{_esc(listing["category"])}' if listing.get("availability"): chips += f'{_esc(listing["availability"])}' for key in ("material", "color"): if listing.get(key): chips += f'{_esc(key.capitalize())}: {_esc(listing[key])}' shop_link = _safe_link(listing.get("shop_url")) shop_html = "" if listing.get("shop"): shop_html = ( f'
Sold by {_esc(listing["shop"])}
' if shop_link else f'
Sold by {_esc(listing["shop"])}
' ) description = str(listing.get("description") or "") description_html = "" if description: shown = description if len(description) <= 900 else description[:900].rstrip() + "…" description_html = ( f'
Description
' f'
{_esc(shown).replace(chr(10), "
")}
' ) review_html = "" if reviews: cards = "" for review in reviews: cards += ( '
' f'
{_stars(review.get("rating"))}' f'{_esc(review.get("author") or "Etsy buyer")}' f'{_esc(review.get("date"))}
' + (f'
{_esc(review.get("text"))}
' if review.get("text") else "") + "
" ) review_html = ( f'
Reviews on the page ({len(reviews)})
{cards}
' ) actions = _button("Open on Etsy", _safe_link(listing.get("url")), primary=True) + _button( "Visit shop", shop_link ) return ( '
' f'
{hero}
' '
' f'
{_esc(listing.get("name"))}
' + (f'
{_esc(price)}
' if price else "") + _rating_line(listing.get("rating"), listing.get("review_count")) + shop_html + (f'
{chips}
' if chips else "") + (f'
{actions}
' if actions else "") + description_html + (f'
Photos
' if thumbs else "") + review_html + "
" ) def _detail_row(listing: Dict[str, Any]) -> Dict[str, Any]: return { "listing_id": listing.get("listing_id"), "name": listing.get("name"), "shop": listing.get("shop"), "category": listing.get("category"), "price": listing.get("price"), "price_high": listing.get("price_high"), "currency": listing.get("currency"), "availability": listing.get("availability"), "rating": listing.get("rating"), "review_count": listing.get("review_count"), "image_count": len(listing.get("images") or []), "main_image": (listing.get("images") or [None])[0], "url": listing.get("url"), "description": listing.get("description"), } def _review_rows(reviews: List[Dict[str, Any]]) -> List[Dict[str, Any]]: return [ { "position": r.get("position"), "listing_id": r.get("listing_id"), "review_id": r.get("review_id"), "rating": r.get("rating"), "date": r.get("date"), "author": r.get("author"), "text": r.get("text"), } for r in reviews ] # ---------------------------------------------------------------- handlers LISTING_TABLE_HEADERS = ["#", "Name", "Price", "Was", "Rating", "Reviews", "Shop ID", "Flags", "URL"] BULK_TABLE_HEADERS = ["Listing ID", "Name", "Shop", "Price", "Rating", "Reviews", "Availability", "URL"] REVIEW_TABLE_HEADERS = ["#", "Rating", "Date", "Author", "Review"] def _picker(choices: List[Tuple[str, str]]) -> Any: return gr.Dropdown(choices=choices, value=None, visible=bool(choices)) def _flags(item: Dict[str, Any]) -> str: parts = [] if item.get("is_ad"): parts.append("Ad") if item.get("bestseller"): parts.append("Bestseller") if item.get("star_seller"): parts.append("Star Seller") if item.get("free_shipping"): parts.append("Free shipping") if item.get("only_left"): parts.append(f"Only {item['only_left']} left") return ", ".join(parts) def run_search( token: str, query: str, country: str, pages: float, sort_by: str, min_price: Optional[float], max_price: Optional[float], free_shipping: bool, ) -> Tuple[str, str, List[List[Any]], Dict[str, Any], Optional[str], Any, List[str]]: tool = _tool_or_none(token) if tool is None: return NO_TOKEN_MD, "", [], {}, None, _picker([]), [] if not query or not query.strip(): return ( "Type what you're looking for, e.g. `personalized leather wallet`, or paste an Etsy category link.", "", [], {}, None, _picker([]), [], ) data = tool.search_listings( query, country, int(pages or 1), sort_by, min_price, max_price, bool(free_shipping) ) if data.get("status") != "success": return _error_md(data), "", [], data, None, _picker([]), [] listings = data.get("listings") or [] rows = _listing_rows(listings) prices = [i["price"] for i in listings if _num(i.get("price")) is not None] ratings = [i["rating"] for i in listings if _num(i.get("rating")) is not None] parts = [f"**{len(listings)}** listings"] if prices: parts.append(f"price **{min(prices):,.2f}** to **{max(prices):,.2f}**, average **{sum(prices) / len(prices):,.2f}**") if ratings: parts.append(f"average rating **{sum(ratings) / len(ratings):.1f}**") ads = sum(1 for i in listings if i.get("is_ad")) if ads: parts.append(f"**{ads}** are ads") summary = " · ".join(parts) + f"\n\n{data.get('pages_fetched')} page(s) · {data.get('credits_used')} credits used" if data.get("warnings"): summary += "\n\n" + "\n".join(f"- {w}" for w in data["warnings"]) table = [ [ r["position"], r["name"], _money(r["price"], r["currency"]), _money(r["original_price"], r["currency"]), r["rating"], r["review_count"], r["shop_id"], _flags(listings[idx]), r["url"], ] for idx, r in enumerate(rows) ] choices = [ (f"{i.get('position')}. {str(i.get('name') or 'Untitled')[:80]}", str(i["url"])) for i in listings if i.get("url") ] urls = [str(i["url"]) for i in listings if i.get("url")] csv_path = _write_csv(rows, "etsy-listings") return summary, render_listings(listings), table, data, csv_path, _picker(choices), urls def send_to_details(picked: Optional[str], current: str) -> Tuple[str, str]: if not picked: return current, "" return picked, "Sent. Open the **Listing details** tab and press the button." def send_to_bulk(urls: List[str]) -> Tuple[str, str]: if not urls: return "", "Run a search first." chosen = urls[:MAX_BULK] return "\n".join(chosen), f"Sent {len(chosen)} listing(s) to the **Bulk compare** tab ({len(chosen) * 10} credits to fetch them)." def run_listing( token: str, ref: str, country: str ) -> Tuple[str, str, List[List[Any]], Dict[str, Any], Optional[str]]: tool = _tool_or_none(token) if tool is None: return NO_TOKEN_MD, "", [], {}, None if not ref or not ref.strip(): return "Paste an Etsy listing link or its numeric listing ID.", "", [], {}, None data = tool.listing_details(ref, country) if data.get("status") != "success": return _error_md(data), "", [], data, None listing = data.get("listing") or {} reviews = data.get("reviews") or [] summary = f"{data.get('credits_used')} credits used." if reviews: summary += f" **{len(reviews)}** review(s) were on the page." else: summary += " Etsy showed no reviews on the page." summary += f"\n\n{data.get('reviews_note')}" rows = _review_rows(reviews) table = [[r["position"], r["rating"], r["date"], r["author"], (r["text"] or "")[:160]] for r in rows] csv_rows = [_detail_row(listing)] csv_path = _write_csv(csv_rows, "etsy-listing") return summary, render_listing(listing, reviews), table, data, csv_path def run_bulk( token: str, refs_text: str, country: str ) -> Tuple[str, List[List[Any]], Dict[str, Any], Optional[str]]: tool = _tool_or_none(token) if tool is None: return NO_TOKEN_MD, [], {}, None refs = [r for r in re.split(r"[\s,]+", refs_text or "") if r] if not refs: return "Paste one Etsy listing link or ID per line.", [], {}, None data = tool.listings_bulk(refs, country) if data.get("status") != "success": return _error_md(data), [], data, None listings = data.get("listings") or [] rows = [_detail_row(l) for l in listings] table = [ [ r["listing_id"], r["name"], r["shop"], _money(r["price"], r["currency"]), r["rating"], r["review_count"], r["availability"], r["url"], ] for r in rows ] lines = [f"**{len(listings)}** listing(s) fetched · {data.get('credits_used')} credits used"] if data.get("warnings"): lines.append("\n".join(f"- {w}" for w in data["warnings"])) if data.get("errors"): lines.append( "**Could not fetch:**\n" + "\n".join(f"- `{_esc(e['ref'])}` — {e['error']}" for e in data["errors"]) ) return "\n\n".join(lines), table, data, _write_csv(rows, "etsy-bulk") # ----------------------------------------------------------------------- UI STYLE = """ """ HERO = f"""
{TAG_SVG.format(size=84)}

{TAG_SVG.format(size=30)} Etsy Scraper

Search Etsy like a shopper and get every listing back as clean data: names, prices, discounts, ratings, review counts, shop IDs and Star Seller / free shipping / Bestseller flags, ready to download as CSV. Then open any listing for its full details and the reviews on its page.

Etsy sits behind DataDome, one of the strictest bot filters around. This Space goes through the Scrape.do API, which handles residential proxies, TLS fingerprints and localized pricing, so there is no browser to run. Use it for price tracking, niche and competitor research, or to give an AI agent live marketplace data.

Get a free API token →
""" CREDIT_NOTE = """
Every Etsy page costs 10 credits: one search or category page (about 48 listings) or one listing's details. The free 1,000 credits cover about 100 pages. The exact cost of each call is read from Scrape.do and shown under the results.
""" FOOTER_MD = f""" --- ### Use it as a smolagents Tool ```python from smolagents import CodeAgent, InferenceClientModel from tool import ScrapeDoEtsyTool agent = CodeAgent( tools=[ScrapeDoEtsyTool(api_token="YOUR_SCRAPEDO_TOKEN")], model=InferenceClientModel(), ) agent.run("Find the 10 cheapest handmade ceramic mugs on Etsy with free shipping and a rating above 4.8.") ``` Or set `SCRAPE_DO_API_TOKEN` in the environment and instantiate with no arguments. Prefer to write the scraper yourself? The [Etsy scraping guide](https://scrape.do/blog/etsy-scraping/) walks through it in Python. [Scrape.do](https://scrape.do/) · [Documentation](https://scrape.do/documentation/) · [Sign up free]({SCRAPE_DO_SIGNUP_URL}) *Independent tool, not affiliated with or endorsed by Etsy. Scrape only public data and follow Etsy's terms and the law where you live.* """ def build_demo() -> gr.Blocks: with gr.Blocks(title="Etsy Scraper — Scrape.do") as demo: gr.HTML(STYLE) gr.HTML(HERO) found_urls = gr.State([]) with gr.Row(): api_token = gr.Textbox( label="Scrape.do API token", placeholder="Paste your token here", type="password", info="Free tier: 1,000 credits a month, about 100 pages.", scale=3, ) country = gr.Dropdown( label="Market", choices=COUNTRY_CHOICES, value="us", info="Sets the currency, language and shipping country.", scale=1, ) gr.HTML(CREDIT_NOTE) with gr.Tabs(): with gr.Tab("Search & categories"): with gr.Row(): query = gr.Textbox( label="Search phrase, or an Etsy category / search / shop link", placeholder="personalized leather wallet or https://www.etsy.com/c/jewelry", scale=3, ) pages = gr.Slider( label="Pages", minimum=1, maximum=MAX_SEARCH_PAGES, step=1, value=1, info="About 48 listings per page, 10 credits each.", scale=1, ) with gr.Row(): sort_by = gr.Dropdown(label="Sort by", choices=SORT_CHOICES, value="relevance") min_price = gr.Number(label="Min price (optional)", value=None, minimum=0) max_price = gr.Number(label="Max price (optional)", value=None, minimum=0) free_shipping = gr.Checkbox(label="Free shipping only", value=False) search_btn = gr.Button("Search Etsy", variant="primary") search_summary = gr.Markdown() listings_view = gr.HTML() listings_table = gr.Dataframe(headers=LISTING_TABLE_HEADERS, wrap=True, label="Listings") listings_csv = gr.File(label="Download the full list as CSV") with gr.Row(): pick = gr.Dropdown( label="Open one of these in the Listing details tab", choices=[], value=None, visible=False, scale=3, ) to_bulk_btn = gr.Button("Send the first 20 to Bulk compare", scale=1) pick_note = gr.Markdown() with gr.Accordion("Raw JSON response", open=False): listings_json = gr.JSON() with gr.Tab("Listing details"): listing_ref = gr.Textbox( label="Etsy listing link or listing ID", placeholder="https://www.etsy.com/listing/4306368113/… or 4306368113", ) listing_btn = gr.Button("Get listing details", variant="primary") listing_summary = gr.Markdown() listing_view = gr.HTML() reviews_table = gr.Dataframe(headers=REVIEW_TABLE_HEADERS, wrap=True, label="Reviews on the page") listing_csv = gr.File(label="Download the listing as CSV") with gr.Accordion("Raw JSON response", open=False): listing_json = gr.JSON() with gr.Tab("Bulk compare"): gr.Markdown( f"One Etsy listing link or ID per line, up to {MAX_BULK}. Each listing costs 10 credits. " "You get one comparison table and a CSV: price, rating, shop and availability side by side." ) bulk_refs = gr.Textbox( label="Listing links or IDs", lines=6, placeholder="https://www.etsy.com/listing/4306368113/…\n4306368113", ) bulk_btn = gr.Button("Fetch all", variant="primary") bulk_summary = gr.Markdown() bulk_table = gr.Dataframe(headers=BULK_TABLE_HEADERS, wrap=True, label="Listings") bulk_csv = gr.File(label="Download the comparison as CSV") with gr.Accordion("Raw JSON response", open=False): bulk_json = gr.JSON() search_inputs = [api_token, query, country, pages, sort_by, min_price, max_price, free_shipping] search_outputs = [ search_summary, listings_view, listings_table, listings_json, listings_csv, pick, found_urls, ] search_btn.click(fn=run_search, inputs=search_inputs, outputs=search_outputs) query.submit(fn=run_search, inputs=search_inputs, outputs=search_outputs) pick.change(fn=send_to_details, inputs=[pick, listing_ref], outputs=[listing_ref, pick_note]) to_bulk_btn.click(fn=send_to_bulk, inputs=[found_urls], outputs=[bulk_refs, pick_note]) listing_inputs = [api_token, listing_ref, country] listing_outputs = [listing_summary, listing_view, reviews_table, listing_json, listing_csv] listing_btn.click(fn=run_listing, inputs=listing_inputs, outputs=listing_outputs) listing_ref.submit(fn=run_listing, inputs=listing_inputs, outputs=listing_outputs) bulk_btn.click( fn=run_bulk, inputs=[api_token, bulk_refs, country], outputs=[bulk_summary, bulk_table, bulk_json, bulk_csv], ) gr.Markdown(FOOTER_MD) return demo # Hugging Face Spaces launches the module-level `demo` object rather than # calling launch() itself, so build it at import time. demo = build_demo() if __name__ == "__main__": demo.launch()