# Yahoo Auctions Japan Scraper – Live, Sold & Flea Market (`datalab-jp/yahoo-auctions-flea-market-scraper`) Actor

Scrape Yahoo! Auctions Japan (open and sold) and Yahoo! Flea Market (ex-PayPay Flea Market) in one Actor. Multi-keyword and URL input, category, condition, price, buy-now, free-shipping and prefecture filters, ending-soon and minimum-bid lists, exclude keywords, seller ratings and item details.

- **URL**: https://apify.com/datalab-jp/yahoo-auctions-flea-market-scraper.md
- **Developed by:** [Task Data](https://apify.com/datalab-jp) (community)
- **Categories:** E-commerce, Automation, Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 listing results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Yahoo Auctions Japan Scraper – Live, Sold & Flea Market

Extract **open auctions, closed (sold) auctions and Yahoo! Flea Market listings** from Japan's largest auction ecosystem in one Actor — [Yahoo! Auctions](https://auctions.yahoo.co.jp/) (ヤフオク!) and [Yahoo! Flea Market](https://paypayfleamarket.yahoo.co.jp/) (Yahoo!フリマ, formerly PayPay Flea Market). Get **titles, current bid / buy-now / final prices, bid and watch counts, end times, condition grades, seller ratings, shipping origin, photos, descriptions and timestamps**. Search by **several keywords or Yahoo URLs**, narrow with **category, condition, price, buy-now, free-shipping, prefecture, ending-soon and minimum-bid filters**, drop noise with **exclude keywords**, and switch on **item-detail enrichment**. Built for international resellers, proxy-buying (代購) services, price researchers, snipers and AI agents. No coding required.

### What data can you extract?

Every row is one listing. Listing-level fields come from Yahoo's search results; detail fields are filled when `fetchItemDetails` is on or when you pass an item URL.

| Field | Description |
|-------|-------------|
| `marketplace`, `retrievedFrom` | `yahoo_auctions` or `yahoo_fleamarket` (where the item is listed) and which API returned it |
| `itemId`, `url`, `title` | Auction ID (`x1234…`) or flea-market ID (`z1234…`), link, title (Japanese) |
| `price`, `priceType`, `currency` | Yen; `current_bid`, `buy_now`, `listed` or `final` |
| `status`, `sourceStatus` | `selling`, `sold` or `ended` (closed auction without a bid); Yahoo's raw value |
| `saleFormat`, `sellerType` | `auction` or `fixed`; `individual` or `store` |
| `condition`, `conditionCode`, `conditionSource` | Japanese label; `new` / `like_new` / `good` / `fair` / `poor`; Yahoo's raw code |
| `bidCount`, `bidderCount`, `buyNowPrice`, `startPrice`, `quantity`, `watchCount` | Auction figures (bidders and quantity from details) |
| `endTime`, `timeLeftSeconds`, `endedAt`, `createdAt` | End time, seconds left for open auctions, end/sale time for sold rows, listing start |
| `shippingIncluded`, `shippingFromArea`, `shippingMethod`, `shippingDuration` | Seller-paid **domestic** shipping flag, prefecture, method and lead time (method/lead time from details) |
| `sellerId`, `sellerName`, `sellerPositiveRatingPercent`, `sellerNumRatings` | Seller ID, display name (details), positive-rating share 0–100, rating count |
| `categoryId`, `categoryPath`, `brandId`, `brandName` | Category (auction and flea numbering differ), brand when present |
| `numLikes`, `numViews`, `description`, `imageUrl`, `imageUrls` | Likes (flea), page views (flea details), full description (details), photos |
| `keyword`, `keywordUsed`, `keywordMapped`, `sourceUrl` | What you asked for, what was searched, alias flag, URL a row came from |
| `detailFetched`, `detailStatus`, `scrapedAt` | Whether enriched (`not_requested` / `fetched` / `failed` / `skipped_budget`) and when |

Rows are unique per `marketplace + itemId` within a run. Flea-market items that Yahoo! Auctions search also surfaces are labelled `yahoo_fleamarket` and returned once.

### Why scrape Yahoo! Auctions and Yahoo! Flea Market?

- **Sold-price research (comps)** — `status: ["sold_out"]` returns closed auctions with at least one bid and sold flea-market items, newest first: real transaction prices for any keyword, brand or category.
- **Sniping and ending-soon lists** — `sortBy: "endTime"` with `endingWithinMinutes` and `minBids` surfaces contested auctions closing in the next hour.
- **Sourcing for resale and 代購** — filter by condition, price band, buy-now availability, free domestic shipping and shipping prefecture; exclude bulk lots (`まとめ売り`) and junk.
- **Due diligence before bidding** — seller positive-rating share and count, shipping origin, full description and photos with `fetchItemDetails`, or paste item URLs to check specific lots.
- **Category and brand sweeps** — paste a Yahoo search URL with the filters you set on the website, or pass category IDs directly.
- **AI agents / RAG** — structured Japanese auction data for LLM workflows. This Actor is discoverable and callable through the [Apify MCP server](https://mcp.apify.com/).

### How to use it (no coding)

1. Click **Start** (or **Try for free**).
2. Enter one or more **Search keywords** — Japanese terms match best, e.g. `ガンプラ`, `iPhone 15`, `ポケモンカード`.
3. Pick the **Listing status** (on sale, sold) and **Max items** per keyword.
4. Open **Advanced** to choose one marketplace, paste Yahoo URLs, add filters, and tick **Fetch item details** when you need descriptions, photos and seller details.
5. Click **Start** and download JSON, CSV or Excel — or read results through the API. A per-input summary is saved to the key-value store as `SEARCH_REPORT`.

### Input example

```json
{
  "keywords": ["ガンプラ", "MG ガンダム"],
  "status": ["sold_out"],
  "condition": ["new", "like_new"],
  "excludeKeywords": ["まとめ売り", "ジャンク"],
  "priceMin": 3000,
  "maxItems": 200
}
```

Ending-soon list (auctions only):

```json
{
  "keywords": ["iPhone"],
  "marketplaces": ["yahoo_auctions"],
  "sortBy": "endTime",
  "endingWithinMinutes": 60,
  "minBids": 1,
  "maxItems": 100
}
```

By URL:

```json
{
  "startUrls": [
    { "url": "https://auctions.yahoo.co.jp/closedsearch/closedsearch?p=ガンプラ&auccat=2084048352&aucminprice=3000" },
    { "url": "https://auctions.yahoo.co.jp/jp/auction/e1240575776" },
    { "url": "https://paypayfleamarket.yahoo.co.jp/item/z665408218" }
  ],
  "maxItems": 100
}
```

All fields are optional. Running with no input performs a health-check search for `ガンプラ` (on sale, both marketplaces, 100 items).

### Output example

A sold flea-market listing with details fetched:

```json
{
  "marketplace": "yahoo_fleamarket",
  "retrievedFrom": "yahoo_auctions_api",
  "itemId": "z676698594",
  "title": "HG 1/144 ゲルググ　ゲルググキャノン　量産型　腕　ガンプラ　プラモデル",
  "price": 640,
  "currency": "JPY",
  "priceType": "final",
  "status": "sold",
  "sourceStatus": "SOLD",
  "sellerType": "individual",
  "saleFormat": "fixed",
  "condition": "傷や汚れあり",
  "conditionCode": "poor",
  "conditionSource": "used60",
  "categoryId": "2317",
  "categoryPath": "ゲーム、おもちゃ > 模型、プラモデル > ロボット",
  "brandId": "101505",
  "brandName": "BANDAI",
  "sellerId": "p12345678",
  "sellerName": "はなとて",
  "sellerStarRating": null,
  "sellerPositiveRatingPercent": 100,
  "sellerNumRatings": 41,
  "shippingIncluded": true,
  "shippingMethod": "おてがる配送（日本郵便）",
  "shippingFromArea": "福岡県",
  "shippingDuration": "1〜2日で発送",
  "bidCount": 1,
  "bidderCount": null,
  "buyNowPrice": 640,
  "startPrice": null,
  "quantity": null,
  "watchCount": 0,
  "endTime": "2026-09-09T10:06:08.000Z",
  "timeLeftSeconds": null,
  "endedAt": "2026-09-09T10:06:08.000Z",
  "numLikes": 3,
  "numViews": 57,
  "description": "塗装なし・接着なし\n\nご購入の際は、以下の点をご了承の上で…",
  "imageUrl": "https://auctions.c.yimg.jp/images.auctions.yahoo.co.jp/image/…",
  "imageUrls": ["https://auctions.c.yimg.jp/images.auctions.yahoo.co.jp/image/…"],
  "url": "https://paypayfleamarket.yahoo.co.jp/item/z676698594",
  "createdAt": "2026-09-08T04:12:36.000Z",
  "updatedAt": "2026-09-09T10:06:10.000Z",
  "keyword": "ガンプラ",
  "keywordUsed": "ガンプラ",
  "keywordMapped": false,
  "sourceUrl": null,
  "detailFetched": true,
  "detailStatus": "fetched",
  "chargeStatus": null,
  "scrapedAt": "2026-09-09T10:10:03.418Z"
}
```

#### SEARCH\_REPORT (key-value store)

Every run writes a `SEARCH_REPORT` record with, per keyword or URL: `scanned`, `excludedByFilter`, `duplicatesSkipped`, `listingsReturned`, `detailFailed`, a `status` (`ok`, `partial`, `not_found`, `scan_limit_reached`, `skipped_limit`, `detail_failed`, `blocked_suspected`, `unexpected_response`, `request_failed`, `unsupported_filter`), a plain-language `hint`, and per search (marketplace × status) the total Yahoo reported, the effective sort, exclusion counts by reason, and why scanning stopped (`end_of_results`, `max_items`, `share_limit`, `scan_limit`, `deadline`, `max_total_items`). Zero results are never silent.

### Data guarantees

- **One row per listing, unique by `marketplace + itemId` within a run.** Use the pair as your idempotency key when merging runs.
- **Zero results cost nothing.** There is no start fee; you pay only for listings actually returned (and for detail pages actually fetched).
- **Detail is billed only on success.** If an item page cannot be fetched, the row keeps its listing-level fields (`detailStatus: failed`) and no `item-detail` event is charged; item URLs that cannot be fetched produce no row and are explained in `SEARCH_REPORT`.
- **Filters are enforced on returned rows, not just requested from Yahoo.** Excluded rows never count toward `maxItems`; scanning is bounded by `maxScannedPerSearch` so a strict filter cannot run away.
- **Hard cost caps.** `maxItems` per keyword/URL (across marketplaces and statuses), `maxTotalItems` per run.
- **Sold means sold.** Closed auctions are returned as `sold` only when they received at least one bid; bid-less closed auctions are `ended`. Flea-market rows are `sold` when Yahoo marks them SOLD. The price shown is the listing's final figure as Yahoo reports it, not a settled payment amount.
- **Japanese labels throughout**, with machine-readable codes beside them.

### Scheduling & automation

- **Sold-price monitor**: `status: ["sold_out"]` sorts newest-ended first on both marketplaces; keep the highest `endedAt` you have processed and treat anything newer as new.
- **Ending-soon feed**: schedule the ending-soon example every 15–30 minutes; `timeLeftSeconds` is computed at scrape time.
- **Webhooks and integrations**: connect a run-finished webhook to Slack, Discord, Zapier or Make, or push the dataset to Google Sheets, from the Actor's *Integrations* tab.
- **Public Tasks**: the *Examples* tab has ready-made tasks (ending soon, sold comps, flea-market near-new) you can copy and schedule.

### Performance

Both marketplaces are read through the JSON endpoints their own web clients use, 100 listings per page, three requests in parallel. Measured on the Apify platform (direct connection, 2026-09-09): a 6-listing dual-marketplace run completes in a few seconds; deep paging to offset 5,000 returned no duplicates. Yahoo caps each search at the total it reports (`total` in `SEARCH_REPORT`).

### How much does it cost?

Pay-per-event, no start fee:

| Event | What it is | Price |
|---|---|---|
| Listing result (`apify-default-dataset-item`) | Each listing row returned | $0.004 (FREE plan) · $0.003 (BRONZE) · $0.002 (SILVER and above) |
| Item detail (`item-detail`) | Each row successfully enriched from its item page | $0.008 |

100 listings without details cost about $0.40 on the FREE plan; the same 100 with details about $1.20. Item URLs always fetch details, so each is one listing result plus one item detail. Use `maxItems`, `maxTotalItems` and `maxScannedPerSearch` to bound spend.

### Integrations: API, MCP, and AI agents

This Actor is **read-only**: it reads publicly visible listing data, performs no login, bid, purchase or write action, and is safe for autonomous agents to call.

#### API (curl)

```bash
curl -X POST "https://api.apify.com/v2/acts/datalab-jp~yahoo-auctions-flea-market-scraper/run-sync-get-dataset-items?token=YOUR_APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"keywords": ["ガンプラ"], "status": ["sold_out"], "maxItems": 50}'
```

> Synchronous runs time out after 300 seconds. For large scrapes, use the standard [run endpoint](https://docs.apify.com/api/v2/act-runs-post) and fetch the dataset afterwards.

#### Python (apify-client)

```python
from apify_client import ApifyClient

client = ApifyClient("YOUR_APIFY_TOKEN")
run = client.actor("datalab-jp/yahoo-auctions-flea-market-scraper").call(run_input={
    "keywords": ["ガンプラ"],
    "status": ["sold_out"],
    "maxItems": 50,
})
items = client.dataset(run["defaultDatasetId"]).list_items().items
report = client.key_value_store(run["defaultKeyValueStoreId"]).get_record("SEARCH_REPORT")["value"]
```

#### JavaScript (apify-client)

```javascript
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: 'YOUR_APIFY_TOKEN' });
const run = await client.actor('datalab-jp/yahoo-auctions-flea-market-scraper').call({
    keywords: ['ガンプラ'],
    status: ['sold_out'],
    maxItems: 50,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
```

#### Use with AI agents (MCP)

This Actor is available through the [Apify MCP server](https://mcp.apify.com/) and eligible for agentic payments. Agents can discover it with `search-actors` ("Yahoo Auctions Japan"), read its inputs with `fetch-actor-details`, and run it with `call-actor`. Tips for agents: pass the Japanese product name in `keywords`; pass `status: ["sold_out"]` when asked what something sells for; pass `marketplaces: ["yahoo_auctions"]` before using auction-only sorts or filters; pass item URLs in `startUrls` when the user already has a link; read `SEARCH_REPORT` when a keyword returns nothing.

### Trust & maintenance

- Exercised by an automated weekly health check (real searches on both marketplaces, non-zero results) in addition to Apify's daily Store test.
- Yahoo changes its endpoints from time to time. Breakages reported on the **Issues** tab are answered within two business days, and fixes ship as new builds without changing the input contract.
- The Actor never returns a fabricated empty result: errors and unexpected responses are reported in `SEARCH_REPORT` (`blocked_suspected`, `unexpected_response`, `request_failed`) instead of a silent zero.

### How this Actor relates to our other Yahoo Actors

| Actor | Scope |
|---|---|
| **Yahoo Auctions Japan Scraper – Live, Sold & Flea Market** (this one) | Open and closed auctions **and** Yahoo! Flea Market, filters, details, URL input |
| Yahoo! Auctions Sold Scraper | Closed auctions only, keyword search, original flat schema |
| Japan Flea Market Scraper | Yahoo! Flea Market **and Rakuma**, keyword search — use it when you need Rakuma |

Migrating from the sold scraper: `searchKeyword` → `keywords: [...]`, `status` is `["sold_out"]`, `soldPrice` → `price` with `priceType: "final"`, `auctionId` → `itemId`.

### Related Actors

Same row shape across our Japanese resale family, so results merge cleanly:

- **Mercari Japan Scraper – Listings & Item Details** — Mercari listings, sold comps and item details
- **Japan Flea Market Scraper** — Rakuma & Yahoo! Flea Market
- **Suruga-ya Scraper**, **CardRush TCG Price Scraper**, **Melonbooks Scraper**, **Diskunion Scraper**

### FAQ

**Which marketplace does a row belong to?**
`marketplace` is where the item is listed. Yahoo! Auctions search also returns flea-market listings (IDs starting with `z`); they are labelled `yahoo_fleamarket`, linked to their flea-market page, and de-duplicated against the flea-market search. If you select only `yahoo_auctions`, those rows are excluded.

**Why does my ending-soon search scan many items but return few?**
`minBids` and `endingWithinMinutes` are applied after retrieval (Yahoo has no native parameters). Scanned-but-unreturned items are not billed; raise `maxScannedPerSearch` if you need a longer list.

**Why was my sort rejected?**
`endTime`, `buyNowLow`, `buyNowHigh`, `bidCount` and `watchCount` exist only on Yahoo! Auctions. Set `marketplaces: ["yahoo_auctions"]` to use them; with both marketplaces selected, use `relevance`, `priceLow` or `priceHigh`.

**How do I find category IDs?**
Auctions: the `auccat` value in a Yahoo! Auctions search URL (or paste the URL into `startUrls`). Flea market: the `categoryId` column of any flea-market row. The two numbering systems are different.

**Does `shippingIncluded` cover international shipping?**
No. It reflects Japanese domestic shipping only (`送料無料` on auctions; always seller-paid on the flea market). Forwarding, proxy fees and customs are outside this data.

**Is this legal?**
This Actor reads only publicly visible listing data through the JSON endpoints Yahoo's own web pages use, without logging in or bypassing any access control, at bounded request rates. Seller information is limited to what Yahoo displays publicly on the listing (display name, rating share and count, prefecture). You are responsible for using the data in accordance with applicable laws and Yahoo! JAPAN's terms of service.

**Do I need a proxy?**
By default the Actor connects directly from the Apify platform; the connection can be changed in the input. On 2026-09-09 both endpoints answered filters, deep paging and a 30-request burst without errors this way.

### Compliance & ethics

Read-only; publicly visible listing data only; no login, bid, purchase, message or write action; bounded request volume (100 listings per request, three requests in parallel, retries with back-off). Seller information is limited to the public display name, rating share and count, and prefecture shown on the listing. Use responsibly and in accordance with applicable laws and Yahoo! JAPAN's terms.

# Actor input Schema

## `keywords` (type: `array`):

One or more search terms, each run against every selected marketplace and status, e.g. \['ガンプラ'] or \['Nintendo Switch', 'ポケモンカード']. Japanese terms match the most listings; brand and model names in Latin letters usually work too. If omitted with no `startUrls`, a health-check search for 'ガンプラ' runs. Each keyword is capped by `maxItems` (all markets and statuses combined) and the run by `maxTotalItems`; the same listing is returned once.

## `status` (type: `array`):

Which listings to include: 'on\_sale' (open auctions and current flea-market listings) and/or 'sold\_out' (closed auctions with at least one bid, and sold flea-market items — real transaction prices). Defaults to \['on\_sale']. An empty list is rejected. Closed auctions without a bid are returned with status 'ended' rather than 'sold'.

## `maxItems` (type: `integer`):

Maximum listings returned per keyword or search URL, counted after filters and de-duplication and across all selected marketplaces and statuses, e.g. 100 for a quick look or 1000 for a sweep. Each returned listing is one billable result. Defaults to 100; accepts 1–5000. Scanning also stops at `maxScannedPerSearch` even if fewer rows matched.

## `marketplaces` (type: `array`):

Which Yahoo marketplaces to search, e.g. \['yahoo\_auctions'] for auctions only. Defaults to both. Every row carries `marketplace` (where the item is listed) and `retrievedFrom` (which API returned it); flea-market items that Yahoo! Auctions search also surfaces are labelled yahoo\_fleamarket and de-duplicated. Auction-only sorts and filters (endTime, bidCount, prefecture, buy-now) require \['yahoo\_auctions'].

## `startUrls` (type: `array`):

Yahoo URLs, mixed freely: an auction search URL (https://auctions.yahoo.co.jp/search/search?p=…; p/va/auccat/aucminprice/aucmaxprice are read; /closedsearch/closedsearch means sold), an auction item URL (https://auctions.yahoo.co.jp/jp/auction/x123…), a flea-market search URL (https://paypayfleamarket.yahoo.co.jp/search/ガンプラ) or item URL (…/item/z123…). Only https and the exact Yahoo hosts are accepted; others are skipped and listed in SEARCH\_REPORT. Item URLs always fetch details.

## `excludeKeywords` (type: `array`):

Words that must not appear in the title, e.g. \['まとめ売り', 'ジャンク']. Sent to Yahoo as '-word' (word-level on Yahoo! Auctions, substring on Yahoo! Flea Market) and additionally enforced as a case-insensitive substring match on returned titles, so 'HG' also removes 'HGUC'. Leave empty to exclude nothing. Excluded rows never count toward `maxItems`.

## `condition` (type: `array`):

Condition grades to include on Yahoo's five-step scale, e.g. \['new', 'like\_new'] for near-new stock. Mapped to NEW/USED10/USED20/USED40/USED60 on both marketplaces. Leave empty for every condition. Each row returns the grade as `conditionCode` (this scale), `condition` (Japanese label) and `conditionSource` (Yahoo's raw code).

## `priceMin` (type: `integer`):

Lower price bound in yen, e.g. 3000. For open auctions this is the current bid or buy-now price as Yahoo indexes it; for sold rows the final price. Whole yen, leave empty for no minimum, must not exceed `priceMax`.

## `priceMax` (type: `integer`):

Upper price bound in yen, e.g. 20000. Same price basis as `priceMin`. Whole yen, leave empty for no maximum.

## `auctionCategoryId` (type: `array`):

Yahoo! Auctions category IDs, e.g. \[2084048352] for 模型、プラモデル、ラジコン — the `auccat` value in an auction search URL. Auction and flea-market category numbers are different systems, so this applies to yahoo\_auctions only; use `fleaCategoryId` for Yahoo! Flea Market. Leave empty for all categories; multiple IDs are OR-ed.

## `fleaCategoryId` (type: `array`):

Yahoo! Flea Market genre/category IDs, e.g. \[2317] for ロボット (模型、プラモデル). These are the `category.id` values returned in flea-market rows and are a different numbering from auction categories. Applies to yahoo\_fleamarket only. Leave empty for all categories; multiple IDs are OR-ed.

## `hasBuyNowPrice` (type: `boolean`):

When true, Yahoo! Auctions results are limited to listings that offer a buy-now (即決) price — including auctions that can still be bid on. This is not the same as 'fixed price only'; check `saleFormat` (auction/fixed) if you need that. Ignored for Yahoo! Flea Market, where every listing is a fixed price. Defaults to false.

## `freeShippingOnly` (type: `boolean`):

When true, only auctions flagged 送料無料 (seller pays domestic shipping) are returned. Yahoo! Flea Market listings always include domestic shipping, so they all pass. Defaults to false. International forwarding is never included in any price.

## `prefectureCode` (type: `array`):

JIS prefecture codes 1–47 to restrict Yahoo! Auctions by shipping origin, e.g. \[13] for Tokyo or \[27] for Osaka. Applies to yahoo\_auctions only; when set, flea-market rows are excluded and the exclusion is reported as prefecture\_unsupported\_flea. Leave empty for all prefectures. The origin is returned per row as `shippingFromArea`.

## `endingWithinMinutes` (type: `integer`):

Return only open auctions ending within this many minutes of the run start, e.g. 60 for the next hour — the classic sniping list. Requires sortBy 'endTime' and status including 'on\_sale', and applies to yahoo\_auctions only (set marketplaces to \['yahoo\_auctions']). Leave empty to disable. Scanning stops at the deadline, so scanned-but-unreturned items are not billed.

## `minBids` (type: `integer`):

Keep only auctions with at least this many bids, e.g. 1 to see items with real demand or 5 for contested lots. Applied after retrieval (Yahoo has no native parameter), so it consumes scan budget but not `maxItems`; combine with sortBy 'bidCount' for efficiency. Applies to yahoo\_auctions only. Leave empty to disable.

## `sortBy` (type: `string`):

Result order. 'relevance' uses each marketplace's default (for sold rows Yahoo! Auctions is ordered newest-ended first). 'priceLow'/'priceHigh' work on both marketplaces. 'endTime', 'buyNowLow', 'buyNowHigh', 'bidCount' and 'watchCount' exist only on Yahoo! Auctions — choosing one while yahoo\_fleamarket is selected is rejected as an input error rather than silently falling back. Defaults to 'relevance'.

## `fetchItemDetails` (type: `boolean`):

When true, each listing is enriched from its item page: full description, all photos, seller name and rating detail, shipping methods and lead time (both marketplaces), plus bidder count and quantity for auctions and page views for flea items. Defaults to false (listing-level fields only). Each successfully enriched row is billed as one item-detail event on top of the listing result; failures keep listing-level fields (detailStatus: failed) and are not billed. Item URLs are always enriched.

## `autoRetryKeywordMapping` (type: `boolean`):

When true (default), a keyword that returns zero listings and appears in a small verified alias table (e.g. 宝可梦 → ポケモン, 高达 → ガンダム) is retried once with the Japanese term; `keywordUsed` shows the term actually searched and `keywordMapped` is set to true. The original keyword is always tried first. Set to false to get the plain zero result with a hint in SEARCH\_REPORT.

## `maxScannedPerSearch` (type: `integer`):

How many listings one search (keyword × marketplace × status) may read from Yahoo while looking for rows that pass your filters, e.g. 3000 for a strict `minBids` filter. Protects run time and platform cost when filters are selective; when the limit stops a search before any row matched, SEARCH\_REPORT says scan\_limit rather than not\_found. Defaults to 1000; accepts 100–20000.

## `maxTotalItems` (type: `integer`):

Hard cap on listings returned by the entire run across all keywords, URLs, marketplaces and statuses, e.g. 500 for a bounded scheduled job. Defaults to 1000; accepts 1–50000. When reached, the run stops paginating and SEARCH\_REPORT notes totalLimitReached: true.

## `proxyConfiguration` (type: `object`):

Apify Proxy settings. By default the Actor connects directly from the Apify platform: on 2026-09-09 both Yahoo JSON endpoints answered filters, deep paging and a 30-request burst with no errors this way. Enable Apify Proxy here if direct access is ever blocked; with no group chosen Apify's default pool is used, the configuration the sibling Yahoo Actors have run on since 2026-07.

## Actor input object example

```json
{
  "keywords": [
    "ガンプラ"
  ],
  "status": [
    "on_sale"
  ],
  "maxItems": 100,
  "marketplaces": [
    "yahoo_auctions",
    "yahoo_fleamarket"
  ],
  "startUrls": [],
  "excludeKeywords": [],
  "condition": [],
  "auctionCategoryId": [],
  "fleaCategoryId": [],
  "hasBuyNowPrice": false,
  "freeShippingOnly": false,
  "prefectureCode": [],
  "sortBy": "relevance",
  "fetchItemDetails": false,
  "autoRetryKeywordMapping": true,
  "maxScannedPerSearch": 1000,
  "maxTotalItems": 1000,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `listings` (type: `string`):

All scraped listings as dataset items (see dataset schema).

## `searchReport` (type: `string`):

Per-keyword / per-URL summary: match count, listings returned, duplicates skipped, detail failures, a status code (ok, partial, not\_found, mapped\_and\_retried, detail\_failed, skipped\_limit, blocked\_suspected, unexpected\_response, request\_failed) and a plain-language hint.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "keywords": [
        "ガンプラ"
    ],
    "status": [
        "on_sale"
    ],
    "maxItems": 100,
    "marketplaces": [
        "yahoo_auctions",
        "yahoo_fleamarket"
    ],
    "startUrls": [],
    "excludeKeywords": [],
    "condition": [],
    "auctionCategoryId": [],
    "fleaCategoryId": [],
    "hasBuyNowPrice": false,
    "freeShippingOnly": false,
    "prefectureCode": [],
    "sortBy": "relevance",
    "fetchItemDetails": false,
    "autoRetryKeywordMapping": true,
    "maxScannedPerSearch": 1000,
    "maxTotalItems": 1000,
    "proxyConfiguration": {
        "useApifyProxy": false
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("datalab-jp/yahoo-auctions-flea-market-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "keywords": ["ガンプラ"],
    "status": ["on_sale"],
    "maxItems": 100,
    "marketplaces": [
        "yahoo_auctions",
        "yahoo_fleamarket",
    ],
    "startUrls": [],
    "excludeKeywords": [],
    "condition": [],
    "auctionCategoryId": [],
    "fleaCategoryId": [],
    "hasBuyNowPrice": False,
    "freeShippingOnly": False,
    "prefectureCode": [],
    "sortBy": "relevance",
    "fetchItemDetails": False,
    "autoRetryKeywordMapping": True,
    "maxScannedPerSearch": 1000,
    "maxTotalItems": 1000,
    "proxyConfiguration": { "useApifyProxy": False },
}

# Run the Actor and wait for it to finish
run = client.actor("datalab-jp/yahoo-auctions-flea-market-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "keywords": [
    "ガンプラ"
  ],
  "status": [
    "on_sale"
  ],
  "maxItems": 100,
  "marketplaces": [
    "yahoo_auctions",
    "yahoo_fleamarket"
  ],
  "startUrls": [],
  "excludeKeywords": [],
  "condition": [],
  "auctionCategoryId": [],
  "fleaCategoryId": [],
  "hasBuyNowPrice": false,
  "freeShippingOnly": false,
  "prefectureCode": [],
  "sortBy": "relevance",
  "fetchItemDetails": false,
  "autoRetryKeywordMapping": true,
  "maxScannedPerSearch": 1000,
  "maxTotalItems": 1000,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}' |
apify call datalab-jp/yahoo-auctions-flea-market-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,datalab-jp/yahoo-auctions-flea-market-scraper"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/MTUNYFb1zVDbVFsW5/builds/DAJwnLA2elLXVQZaE/openapi.json