eBay Browse API の検索精度を、パラメータ設計で高める

const BASE_URL = "https://api.ebay.com/buy/browse/v1/item_summary/search"
 
async function searchItems(params: URLSearchParams, token: string) {
  const res = await fetch(`${BASE_URL}?${params}`, {
    headers: {
      Authorization: `Bearer ${token}`,
      "X-EBAY-C-MARKETPLACE-ID": "EBAY_US", // 対象マーケットプレイス
      "X-EBAY-C-ENDUSERCTX": "contextualLocation=country=JP", // エンドユーザーのロケーション
    },
  })
  if (!res.ok) throw new Error(`Browse API error: ${res.status}`)
  return res.json()
}
 
const params = new URLSearchParams({
  q: "vintage denim jacket",
  category_ids: "3002", // Men's Clothing
  limit: "50",
  offset: "0",
})
const result = await searchItems(params, accessToken)

// price:[10..50] — 価格帯（ドル）
// conditions:{NEW|LIKE_NEW} — コンディション
// deliveryCountry:JP — 日本への配送あり
// itemLocationCountry:JP — 出品者が日本にいる（越境 EC では外す場合も）
const params = new URLSearchParams({
  q: "vintage denim jacket",
  category_ids: "3002",
  filter: [
    "price:[10..50]",
    "conditions:{NEW|LIKE_NEW}",
    "deliveryCountry:JP",
  ].join(","),
  priceCurrency: "USD",
  limit: "50",
  offset: "0",
})

// aspect_filter の書き方: aspectName:{value1|value2}
// 複数のアスペクトはカンマ区切り（AND）
const params = new URLSearchParams({
  q: "denim jacket",
  category_ids: "3002",
  filter: "conditions:{NEW|LIKE_NEW},deliveryCountry:JP",
  aspect_filter: [
    "Brand:{Levi's|Wrangler}",
    "Size:{M|L|XL}",
    "Color:{Blue|Dark Blue}",
  ].join(","),
  limit: "50",
  offset: "0",
})

// sort の主な選択肢
// BEST_MATCH (デフォルト) — eBay アルゴリズムによる関連度
// PRICE — 価格昇順
// -PRICE — 価格降順
// NEWLY_LISTED — 新着順
// ENDING_SOONEST — 終了間近 (オークション形式)
const params = new URLSearchParams({
  q: "denim jacket",
  category_ids: "3002",
  filter: "conditions:{NEW},deliveryCountry:JP",
  sort: "PRICE",
  fieldgroups: "MATCHING_ITEMS,ASPECT_REFINEMENTS",
  limit: "50",
  offset: "0",
})

async function* paginateSearch(
  baseParams: URLSearchParams,
  token: string,
  pageSize = 50,
) {
  const ABSOLUTE_LIMIT = 10_000 // offset + limit の合計上限
  let offset = 0
 
  while (offset < ABSOLUTE_LIMIT) {
    const params = new URLSearchParams(baseParams)
    params.set("limit", String(pageSize))
    params.set("offset", String(offset))
 
    const data = await searchItems(params, token)
    const items: unknown[] = data.itemSummaries ?? []
 
    if (items.length === 0) break
    yield items
 
    offset += items.length
 
    // total が取得済み件数以下なら終了
    if (data.total <= offset) break
  }
}
 
// 使い方
for await (const page of paginateSearch(baseParams, accessToken)) {
  for (const item of page) {
    // 商品を処理
  }
}

type SearchLog = {
  query: string
  filter: string
  aspectFilter: string
  total: number
  firstPageItemCount: number
  searchedAt: Date
}
 
async function searchWithLogging(
  params: URLSearchParams,
  token: string,
): Promise<{ data: unknown; log: SearchLog }> {
  const start = Date.now()
  const data = await searchItems(params, token)
 
  const log: SearchLog = {
    query: params.get("q") ?? "",
    filter: params.get("filter") ?? "",
    aspectFilter: params.get("aspect_filter") ?? "",
    total: data.total ?? 0,
    firstPageItemCount: (data.itemSummaries ?? []).length,
    searchedAt: new Date(start),
  }
 
  // total が 0 のクエリや firstPageItemCount が極端に少ない場合はアラート対象
  if (log.total === 0 || log.firstPageItemCount < 5) {
    console.warn("low-yield search", log)
  }
 
  return { data, log }
}