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で解析します。呼び出し元は
// まずブラウザー側のスクロール/ waitForFunctionを実行して
// 遅延領域を水和する責任があります。その後、解析は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);
  }

  // settled DOMをcheerioで解析します — `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) 現在の価格としてEtsyがマークした明示的な `[data-selector='price-only']`
  // サブツリーを優先する; (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*(?:中|星|評価)/i);
    if (rm) rating = parseFloat(rm[1]);
  });

// ステータスバッジ — ページ本文を正規表現で処理する。
const bodyText = $("body").text();
const isBestseller = /Bestseller/i.test(bodyText);
const isFreeShipping = /free shipping/i.test(bodyText);
const isStarSeller = /Star Seller/i.test(bodyText);
const inStock = !/out of stock|sold out/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);

  // Node サイド：今や水和されたページを 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;

4つのカードセレクターの選択肢は、Etsyの進行中のA/B改訂をカバーしています。`[data-review-region]`が現在のホットセレクターです。`[class*='review-card']`、`[class*='review-item']`および`li[class*='review']`は、アカウントやリスティングによって表示される古いおよび新しいバリアントです。上部のcardTextの長さガードは、偶然に一致するラッパー要素をスキップし、1つのバッチとして連結されたすべてのレビューを返すことを防ぎます。

**画像。** Etsyはデフォルトでサムネイルを提供します。URLのサイズ接尾辞を置き換えることでフル解像度にアップグレードします：`il_75x75` → `il_fullxfull`、または`_300x300.jpg` → `_1024x1024.jpg`。同じ画像で、はるかに高い解像度、追加のリクエストは不要です。

```ts
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}/${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}/${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 URLs"
  ],
  "variations": [
    { "name": "パーソナライズ", "options": ["はい、彫刻を追加", "いいえ、ありがとう"] },
    { "name": "カラーオプション", "options": ["チェスナット", "ブラック", "タン"] }
  ],
  "breadcrumbs": ["ホームページ", "バッグと財布", "財布とマネークリップ", "財布"],
  "relatedSearches": ["男性用革財布", "スリークメンズ財布", "カスタムスリムレザー二つ折り財布"],
  "listedDate": "2026年4月15日",
  "priceBucket": null,
  "reviews": [
    {
      "author": "Liz",
      "rating": 0,
      "text": "説明通りで、迅速に発送されました。ありがとうございます！",
      "date": "2026年4月12日",
      "itemQuality": null,
      "shipping": null,
      "customerService": null,
      "photos": []
    },
    "... 9 more reviews"
  ],
  "error": null,
  "scrapedAt": "2026年4月16日T17:09:48.919Z"
}

const CONFIG: ScraperInput = {
```json
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"
  },
  // ...
};