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'
"
)
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.
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()