EtsyスクレイパーをScrapeless Scraping Browserで構築する方法：包括的ガイド2026（Node.js）

mkdir etsy-scrapeless-browserless && cd etsy-scrapeless-browserless
npm init -y
npm install puppeteer-core dotenv cheerio
npm install -D tsx typescript @types/node @types/cheerio

SCRAPELESS_API_KEY=your_key_here

import "dotenv/config";
import puppeteer, { type Browser, type Page } from "puppeteer-core";
import * as cheerio from "cheerio";

// ヘルパー — ページのフルHTMLを取得し、cheerioで解析します。呼び出し元
// は、ブラウザ側のスクロール/待機関数の実行を最初に行う責任があります
// その後、Node内での解析が行われます：型付けされ、文字列化された評価ボディは不要
// `__name` tsxの落とし穴もなく、保存したHTMLフィクスチャに対してユニットテストが容易です。
async function parseWithCheerio(page: Page): Promise<cheerio.CheerioAPI> {
  const html = await page.content();
  return cheerio.load(html);
}

type ScraperInput = {
  proxyCountry: string;   // 例: "US", "GB", "DE"
  sessionTTL: number;     // 秒, 60～900が許可されています；600は安全なデフォルト
};

function connectionURL(sessionName: string, cfg: ScraperInput): string {
  const token = process.env.SCRAPELESS_API_KEY;
  if (!token) throw new Error("SCRAPELESS_API_KEYが.envに設定されていません");
  // Scrapelessはデフォルトでセッションの寿命にわたって
  // 住宅IPを固定しますので、puppeteer.connectの一
  // ページナビゲーション内ですべて同じ出力IPが使用されます。
  // 新しいセッション（新しい接続）を開くことで新しいIPが割り当てられ、
  // これが再試行ループがフラグ付けされたIPを回避するために
  // 依存することになります。
  const qs = new URLSearchParams({
    token,
    proxyCountry: cfg.proxyCountry,
    sessionTTL: String(cfg.sessionTTL),
    sessionName,
    sessionRecording: "true",
    // Scrapelessが完全なデスクトップフィンガープリンティング
    // — UA、画面、タイムゾーン言語を所有します。手動でのsetViewport /
    // setUserAgentは不要です。
    fingerprint: JSON.stringify({ platform: "Windows" }),
  });
  return `wss://browser.scrapeless.com/api/v2/browser?${qs.toString()}`;
}

async function openBrowser(sessionName: string, cfg: ScraperInput): Promise<Browser> {
  return puppeteer.connect({
    browserWSEndpoint: connectionURL(sessionName, cfg),
    defaultViewport: null,
  });
}

async function prepPage(page: Page): Promise<void> {
  // tsxで注入された__nameヘルパーをスタブ化して、page.evaluate関数の本体が
  // ブラウザコンテキスト内で「__name is not defined」とならないようにします。
  await page.evaluateOnNewDocument(
    "(function(){ globalThis.__name = function(f){ return f; }; })()",
  );
}

const ETSY_COUNTRY_PATHS: Record<string, string> = {
  US: "", DE: "de/", GB: "uk/", FR: "fr/", IT: "it/", ES: "es/",
  NL: "nl/", CA: "ca/", AU: "au/", JP: "jp/", IN: "in/",
};

async function warmUpSession(page: Page, proxyCountry: string): Promise<void> {
  const path = ETSY_COUNTRY_PATHS[proxyCountry] ?? "";
  try {
    await page.goto(`https://www.etsy.com/${path}`, {
      waitUntil: "domcontentloaded",
      timeout: 30000,
    });
  } catch {
    // タイムアウトやネットワークエラーは問題ありません — この時点でクッキーが設定されます。
  }
  await dismissEtsyConsent(page);
  await delay(1500);
}

const CONFIG: ScraperInput = {
  startUrls: [
    "https://www.etsy.com/listing/547491922/leather-walletwalletman-leather",
    "https://www.etsy.com/listing/1022283131/personalized-slim-wallet-fathers-day",
  ],
  maxProducts: 2,
  // ...他のデフォルト
};

const CONFIG: ScraperInput = {
  categoryUrl: "https://www.etsy.com/c/bags-and-purses/wallets-and-money-clips/wallets",
  filters: {
    onSale: true,
    freeShipping: true,
    minPrice: 20,
    maxPrice: 60,
    orderBy: "most_relevant",
  },
  maxPagesPerQuery: 2,
  maxProducts: 20,
};

const CONFIG: ScraperInput = {
  searchQuery: "leather wallet",
  expandStrategy: "keywords",                   // "none" | "keywords" | "prices"
  expandKeywords: ["mens", "womens", "vintage"], // 拡張 = キーワードの時に基本に追加される
  maxProducts: 20,
};

const CONFIG: ScraperInput = {
  shopUrl: "https://www.etsy.com/shop/TexasValleyLeather",
  maxPagesPerQuery: 5,
  maxProducts: 40,
};

function searchUrlForQuery(query: string, page = 1, priceMin?: number, priceMax?: number) {
  const params = new URLSearchParams({ q: query });
  if (page > 1) params.set("page", String(page));
  if (priceMin !== undefined) params.set("min", String(priceMin));
  if (priceMax !== undefined) params.set("max", String(priceMax));
  return `https://www.etsy.com/search?${params.toString()}`;
}

type ExpandStrategy = "キーワード" | "価格" | "なし";

function multiQueryExpand(
  base: string,
  cfg: { expandStrategy: ExpandStrategy; expandKeywords: string[]; priceBuckets: [number, number][] }
) {
  if (cfg.expandStrategy === "キーワード") {
    const queries = [base, ...cfg.expandKeywords.map((k) => `${k} ${base}`)];
    return queries.map((q) => searchUrlForQuery(q));
  }
  if (cfg.expandStrategy === "価格") {
    return cfg.priceBuckets.map(([min, max]) => searchUrlForQuery(base, 1, min, max));
  }
  return [searchUrlForQuery(base)];
}

type SearchHit = { listingId: string | null; url: string; title: string | null; rank: number };
const delay = (ms: number) => new Promise((r) => setTimeout(r, ms));

async function collectSearchResults(page: Page, searchUrl: string, target: number, pageTimeoutMs = 60000): Promise<SearchHit[]> {
  await page.goto(searchUrl, { waitUntil: "domcontentloaded", timeout: 60000 });
  await dismissEtsyConsent(page);
  await delay(2000);

  // レイジーロードされたカードをトリガーするために数回スクロールします。それぞれのパスは
  // 現在のDOMのcheerioスナップショットを取得し、カードの数をカウントします — 十分な数が揃ったら
  // スクロールを停止します。
  for (let i = 0; i < 6; i++) {
    const $peek = await parseWithCheerio(page);
    if ($peek("[data-listing-id], div.listing-link").length >= target) break;
    await page.evaluate(() => window.scrollBy(0, 1200));
    await delay(900);
  }

  // cheerioを使って安定したDOMをパース — `page.evaluate`の往復なし、
  // 文字列化された関数ボディなし、単に直接セレクタトラバース。
  const $ = await parseWithCheerio(page);
  let cards = $("div.listing-link");
  if (cards.length === 0) cards = $("[data-listing-id]");
  const hits: SearchHit[] = [];
  const seen = new Set<string>();
  cards.each((_, card) => {
    const link = $(card).find('a[href*="/listing/"]').first();
    if (!link.length) return;
    const href = link.attr("href") || "";
    const absolute = href.startsWith("http") ? href : `https://www.etsy.com${href.startsWith("/") ? "" : "/"}${href}`;
    const url = absolute.split("?")[0];
    if (!url || seen.has(url)) return;
    seen.add(url);
    const titleEl = $(card).find("h3").first();
    const title = titleEl.length ? titleEl.text().trim() : (link.attr("title") || null);
    const idMatch = url.match(/\/listing\/(\d+)/);
    const listingId = idMatch ? idMatch[1] : null;
    hits.push({ listingId, url, title, rank: hits.length + 1 });
  });
  return hits;
}

const resp = await page.goto(hit.url, { waitUntil: "domcontentloaded", timeout: 60000 });
const status = resp?.status() ?? 0;
if (status === 403 || status === 429) {
  throw new Error(`ブロックされました: HTTP ${status} on ${hit.url}`);
}
await dismissEtsyConsent(page);
try {
  await page.waitForSelector("h1", { timeout: 15000 });
} catch {
  // 15秒後にh1が表示されない場合はほぼ間違いなくDataDomeのチャレンジまたはリダイレクトページを意味します。
  // リトライループが新しいセッション（=新しい住宅IP）を開くためにエラーを投げます。
  throw new Error(`h1が${hit.url}に存在しない — おそらくボットチャレンジページ`);
}
await delay(1500);

async function extractOverview(page: Page): Promise<Partial<EtsyProduct>> {
  // ブラウザサイド: チャンクでスクロールして説明 / 材料 / 配送が
  // 遅延読み込みされるようにし、「読み込み中」のプレースホルダーを超えて
  // バイボックスがハイドレートされるのを待ちます。
  await page.evaluate(`(function() {
    var step = 500, total = document.body.scrollHeight, current = 0;
    var iv = setInterval(function() {
      current += step;
      window.scrollTo(0, current);
      if (current >= total) clearInterval(iv);
    }, 200);
  })()`);
  await delay(3500);

  try {
    await page.waitForFunction(
      // いかなる妥当な価格ラッパーが数値を含むまで待機
      //（Etsyが短時間表示する「読み込み中」プレースホルダーではなく）。 
      // バイボックスラッパーだけでなく幅広くキャストすることが
      // 価格が最初に.currency-valueにレンダリングされる遅いリスティングでの
      // ヒット率を向上させます。
      `(function(){
        var sels = [
          "[data-selector='price-only'] span.currency-value",
          "div[data-buy-box-region='price'] span.currency-value",
          "p[class*='price'] span.currency-value",
          "span.currency-value"
        ];
        for (var i = 0; i < sels.length; i++) {
          var el = document.querySelector(sels[i]);
          if (el && /^\\s*\\$?\\d/.test((el.textContent || '').trim())) return true;
        }
        return false;
      })()`,
      { timeout: 15000 },
    );
  } catch { /* エクストラクターは以下で最善を尽くします */ }

  // ノードサイド: レンダリングされたHTMLを一度引き出し、cheerioで解析します。
  const $ = await parseWithCheerio(page);

  const title = $("h1").first().text().trim() || null;

  // 価格 — 三段階のカスケード。 (1) 明示的な`[data-selector='price-only']`
  // サブツリーEtsyが現在の価格としてマークすることを優先; (2) 
  // 最初の`span.currency-value`にフォールバック、その先祖が
  // ストライクスルー / オリジナル価格ラッパーではない場合; (3) 
  // 最後の手段ボディテキストの正規表現。
  const isOriginalPriceWrapper = (el: any) =>
    $(el).closest("[class*='strikethrough'], [class*='original'], s, .wt-text-strikethrough").length > 0;
  let price: string | null = null;
  const priceOnly = $("[data-selector='price-only'] span.currency-value").first();
  if (priceOnly.length && /^\d/.test(priceOnly.text().trim())) {
    price = priceOnly.text().trim();
  }
  if (!price) {
    $("span.currency-value").each((_, el) => {
      if (price) return false;
      if (isOriginalPriceWrapper(el)) return;
      const t = $(el).text().trim();
      if (t && /^\d/.test(t)) price = t;
    });
  }
  if (!price) {
    const bodyPriceMatch = $("body").text().match(/(?:今すぐ\s+)?価格:?\s*([$£€]?[\d.,]+)/i);
    if (bodyPriceMatch) price = bodyPriceMatch[1].trim();
  }

  // 評価 — "星"、"評価"、または"中"を含む任意のaria-label。
  let rating: number | null = null;
  $("[aria-label*='star' i], [aria-label*='rating' i]").each((_, n) => {
    if (rating !== null) return false;
    const a = $(n).attr("aria-label") || "";
    const rm = a.match(/(\d+(?:\.\d+)?)\s*(?:out|star|rating)/i);
    if (rm) rating = parseFloat(rm[1]);
  });

// ステータスバッジ — ページ本体を正規表現でチェックします。
  const bodyText = $("body").text();
  const isBestseller = /ベストセラー/i.test(bodyText);
  const isFreeShipping = /送料無料/i.test(bodyText);
  const isStarSeller = /スターセラー/i.test(bodyText);
  const inStock = !/在庫切れ|売り切れ/i.test(bodyText);

  // ショップサイドカー。
  const shopLink = $("a[href*='/shop/']").first();
  const shopName = shopLink.text().trim() || null;
  const shopUrl = (shopLink.attr("href") || "").split("?")[0] || null;

  return { title, _price_raw: price, rating, isBestseller, isFreeShipping, isStarSeller, inStock,
    shop: { name: shopName, url: shopUrl } } as Partial<EtsyProduct>;
}

async function extractReviews(page: Page, max: number): Promise<EtsyReview[]> {
  // ブラウザ側：レビューエリアにスクロールして、遅延読み込みのレビューカードをレンダリングします。
  for (let i = 0; i < 8; i++) {
    const found = await page.evaluate(
      `!!document.querySelector('[data-reviews-section], div#reviews, div[class*="reviews"]')`,
    );
    if (found) break;
    await page.evaluate(() => window.scrollBy(0, 700));
    await delay(700);
  }
  await delay(1500);

  // ノード側：今や水分補給されたページを cheerio で解析します。
  const $ = await parseWithCheerio(page);
  const out: EtsyReview[] = [];

  $(
    "div[data-review-region], div[class*='review-card'], div[class*='review-item'], li[class*='review']",
  ).each((_, card) => {
    if (out.length >= max) return false;
    const $card = $(card);
    const cardText = $card.text();
    // 一度に多くのレビューを保持する集約コンテナはスキップします。
    if (cardText.length > 6000) return;

    const author = $card.find("a[href*='/people/'], strong, p[class*='name']").first().text().trim() || null;

    // 評価: `data-rating` 属性が優先、その後 aria-label をチェックします。
    let rating: number | null = null;
    const $starEl = $card.find("[aria-label*='star' i], [data-rating]").first();
    if ($starEl.length) {
      const dr = $starEl.attr("data-rating");
      if (dr) rating = parseFloat(dr);
      else {
        const rm = ($starEl.attr("aria-label") || "").match(/(\d+(?:\.\d+)?)/);
        if (rm) rating = parseFloat(rm[1]);
      }
    }

    // テキスト: 専用のセレクタ、その後カード内の最も長い段落にチェックします。
    let text: string | null =
      $card.find("p[class*='review-text'], div[class*='review-text'], div[id*='review-content']")
        .first().text().trim() || null;
    if (!text) {
      let longest = "";
      $card.find("p").each((_, p) => {
        const pt = $(p).text().trim();
        if (pt.length > longest.length && pt.length > 20) longest = pt;
      });
      text = longest || null;
    }

    // 日付: 専用の要素を最初に、その後は月名または数値の正規表現。
    let date: string | null =
      $card.find("span[class*='date'], time, p[class*='date']").first().text().trim() || null;
    if (!date) {
      const dm = cardText.match(/(\w{3,9}\s+\d{1,2},?\s+\d{4}|\d{1,2}\/\d{1,2}\/\d{2,4})/);
      if (dm) date = dm[1];
    }

    // サブ評価 — カード内のラベル付き行。ラベルをマッチングし、隣接する数を解析します。
    const subRating = (label: string): number | null => {
      let val: number | null = null;
      $card.find("span, div, li").each((_, row) => {
        if (val !== null) return false;
        const t = $(row).text().toLowerCase();
        if (t.includes(label) && t.length < 60) {
          const sm = t.match(/(\d+(?:\.\d+)?)/);
          if (sm) val = parseFloat(sm[1]);
        }
      });
      return val;
    };

    // レビュアーがアップロードした写真 — リスティング画像と同じ `il_fullxfull` アップグレード。
    const photos: string[] = [];
    const photoSeen = new Set<string>();
    $card.find("img[src*='etsystatic'], img[data-src*='etsystatic']").each((_, img) => {
      if (photos.length >= 6) return false;
      let psrc = $(img).attr("src") || $(img).attr("data-src") || "";
      if (!psrc) return;

async function extractImages(page: Page, max: number): Promise<string[]> {
  const $ = await parseWithCheerio(page);
  const urls: string[] = [];
  const seen = new Set<string>();
  $("img[src*='etsystatic'], img[data-src*='etsystatic']").each((_, img) => {
    if (urls.length >= max) return false;
    let src = $(img).attr("src") || $(img).attr("data-src") || "";
    if (!src) return;
    // 可能な限りサムネイルのサイズサフィックスをフル解像度にアップグレード。
    src = src.replace(/il_\d+xN/, "il_fullxfull").replace(/_\d+x\d+\./, "_1024x1024。");
    if (!seen.has(src)) { seen.add(src); urls.push(src); }
  });
  return urls;
}

// メインループの内部、検索ヒット h ごとに一度実行（i によりインデックス付け）：
const MAX_ATTEMPTS = cfg.maxRetries;   // デフォルト 10
let p: EtsyProduct | null = null;
let lastError: ScrapeErrorInfo | null = null;
let attemptsUsed = 0;
for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
  attemptsUsed = attempt;
  let eb;
  try {
    eb = await openBrowser(`etsy-enrich-${i}-${attempt}-${Date.now()}`, cfg);
  } catch (e: any) {
    lastError = categorizeError(new Error(`openBrowser に失敗しました: ${e?.message ?? e}`));
    log(`    attempt ${attempt}/${MAX_ATTEMPTS} — ${lastError.kind}: ${lastError.message.slice(0, 120)}`);
    if (!lastError.retryable) break;
    if (attempt < MAX_ATTEMPTS) await delay(Math.max(cfg.retryInitialBackoffMs, 3000));
    continue;
  }
  try {
    p = await enrichProduct(eb, h, cfg);
    if (p.title) { lastError = null; break; }
    lastError = categorizeError(new Error(`no h1 on ${h.url} — title was null`));
  } catch (e: any) {
    lastError = categorizeError(e);
    log(`    attempt ${attempt}/${MAX_ATTEMPTS} — ${lastError.kind}: ${lastError.message.slice(0, 120)}`);
    if (!lastError.retryable) break;   // 再試行不可能: 404 など。早めに失敗。
  } finally {
    await eb.close().catch(() => {});
  }
  if (attempt < MAX_ATTEMPTS) {
    // 設定可能な成長バックオフ。デフォルト (3000, 1500, 500) では
    // 5秒、8秒、12秒、17秒、23秒、30秒、38秒、47秒、57秒の間隔が得られます。
    const backoff = cfg.retryInitialBackoffMs
      + attempt * (cfg.retryBackoffLinearMs + attempt * cfg.retryBackoffQuadraticMs);
    await delay(backoff);
  }
}
if (!p || !p.title) {
  p = emptyProduct(h.url);
  p.rank = h.rank;
  if (lastError) {
    p.error = { kind: lastError.kind, message: lastError.message.slice(0, 200), attempts: attemptsUsed };
  }
}
products.push(p);
// 製品間のポーズ（設定可能） — 連続したリストのナビゲーションを分割し、セッションパターンが DataDome によってボットの形に見えないようにします。
if (i < hits.length - 1) await delay(cfg.interProductDelayMs);

{
  "listingId": "547491922",

{
  "title": "レザー財布•財布•メンズレザー財布•ミニマリスト財布•パーソナライズ財布•レザー記念日•スリムレザー財布•メンズ財布",
  "url": "https://www.etsy.com/listing/547491922/leather-walletwalletman-leather",
  "rank": 1,
  "price": 5.52,
  "originalPrice": 68.99,
  "currency": "¥",
  "discountPercent": 92,
  "inStock": false,
  "rating": 4.9,
  "reviewsCount": 929,
  "favoritesCount": 850,
  "isBestseller": false,
  "isFreeShipping": false,
  "isStarSeller": true,
  "tags": ["花嫁介添えギフト", "新郎仲間ギフト", "結婚式ギフト", "婚約ギフト"],
  "materials": [],
  "shop": {
    "name": "TexasValleyLeather",
    "url": "https://www.etsy.com/shop/TexasValleyLeather",
    "location": null,
    "totalSales": null,
    "openedYear": null,
    "reviewsCountShop": null
  },
  "images": [
    "https://i.etsystatic.com/15980284/r/il/2456a5/3164786673/il_fullxfull.3164786673_roeh.jpg",
    "... 4 more URL"
  ],
  "variations": [
    { "name": "カスタマイズ", "options": ["はい、エングレービングを追加", "いいえ、ありがとう"] },
    { "name": "色の選択肢", "options": ["栗色", "黒", "タン"] }
  ],
  "breadcrumbs": ["ホームページ", "バッグと財布", "財布とマネークリップ", "財布"],
  "relatedSearches": ["メンズレザー財布", "スリークメンズ財布", "カスタムスリムレザー二つ折り財布"],
  "listedDate": "2026年4月15日",
  "priceBucket": null,
  "reviews": [
    {
      "author": "リズ",
      "rating": 0,
      "text": "説明通りで迅速に発送されました。ありがとう！",
      "date": "2026年4月12日",
      "itemQuality": null,
      "shipping": null,
      "customerService": null,
      "photos": []
    },
    "... 9 件のレビューがあります"
  ],
  "error": null,
  "scrapedAt": "2026-04-16T17:09:48.919Z"
}

const CONFIG: ScraperInput = {
  categoryUrl: "https://www.etsy.com/c/bags-and-purses/wallets-and-money-clips/wallets",
  filters: {
    onSale: true,           // → &is_on_sale=1
    freeShipping: true,     // → &free_shipping=1
    customizable: true,     // → &is_personalizable=1
    shipsTo: "US",          // → &ships_to=US (ISO国コード)
    minPrice: 20,           // → &min=20
    maxPrice: 60,           // → &max=60
    condition: "vintage",   // "new" | "vintage" (→ &explicit=vintage)
    orderBy: "price_asc",   // "most_relevant" | "date_desc" | "price_asc" | "price_desc" | "highest_reviews"
  },
  // ...
};