{
  "openapi": "3.0.1",
  "info": {
    "title": "Yahoo Auctions Japan Scraper – Live, Sold & Flea Market",
    "description": "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.",
    "version": "0.0",
    "x-build-id": "DAJwnLA2elLXVQZaE"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/datalab-jp~yahoo-auctions-flea-market-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-datalab-jp-yahoo-auctions-flea-market-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/acts/datalab-jp~yahoo-auctions-flea-market-scraper/runs": {
      "post": {
        "operationId": "runs-sync-datalab-jp-yahoo-auctions-flea-market-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor and returns information about the initiated run in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/runsResponseSchema"
                }
              }
            }
          }
        }
      }
    },
    "/acts/datalab-jp~yahoo-auctions-flea-market-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-datalab-jp-yahoo-auctions-flea-market-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "inputSchema": {
        "type": "object",
        "properties": {
          "keywords": {
            "title": "Search keywords",
            "type": "array",
            "description": "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.",
            "default": [
              "ガンプラ"
            ],
            "items": {
              "type": "string"
            }
          },
          "status": {
            "title": "Listing status",
            "uniqueItems": true,
            "type": "array",
            "description": "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'.",
            "items": {
              "type": "string",
              "enum": [
                "on_sale",
                "sold_out"
              ],
              "enumTitles": [
                "On sale / open",
                "Sold / closed (price research)"
              ]
            },
            "default": [
              "on_sale"
            ]
          },
          "maxItems": {
            "title": "Max items per keyword / URL",
            "minimum": 1,
            "maximum": 5000,
            "type": "integer",
            "description": "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.",
            "default": 100
          },
          "marketplaces": {
            "title": "Marketplaces",
            "uniqueItems": true,
            "type": "array",
            "description": "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'].",
            "items": {
              "type": "string",
              "enum": [
                "yahoo_auctions",
                "yahoo_fleamarket"
              ],
              "enumTitles": [
                "Yahoo! Auctions (ヤフオク)",
                "Yahoo! Flea Market (Yahoo!フリマ, ex-PayPay Flea Market)"
              ]
            },
            "default": [
              "yahoo_auctions",
              "yahoo_fleamarket"
            ]
          },
          "startUrls": {
            "title": "Start URLs",
            "type": "array",
            "description": "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.",
            "default": [],
            "items": {
              "type": "object",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "title": "URL of a web page",
                  "format": "uri"
                }
              }
            }
          },
          "excludeKeywords": {
            "title": "Exclude keywords",
            "type": "array",
            "description": "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`.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "condition": {
            "title": "Condition",
            "uniqueItems": true,
            "type": "array",
            "description": "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).",
            "items": {
              "type": "string",
              "enum": [
                "new",
                "like_new",
                "good",
                "fair",
                "poor"
              ],
              "enumTitles": [
                "新品、未使用 (new)",
                "未使用に近い (like new)",
                "目立った傷や汚れなし (good)",
                "やや傷や汚れあり (fair)",
                "傷や汚れあり (poor)"
              ]
            },
            "default": []
          },
          "priceMin": {
            "title": "Minimum price (JPY)",
            "type": "integer",
            "description": "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": {
            "title": "Maximum price (JPY)",
            "type": "integer",
            "description": "Upper price bound in yen, e.g. 20000. Same price basis as `priceMin`. Whole yen, leave empty for no maximum."
          },
          "auctionCategoryId": {
            "title": "Yahoo! Auctions category IDs",
            "type": "array",
            "description": "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.",
            "default": []
          },
          "fleaCategoryId": {
            "title": "Yahoo! Flea Market category IDs",
            "type": "array",
            "description": "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.",
            "default": []
          },
          "hasBuyNowPrice": {
            "title": "Buy-now price available (auctions)",
            "type": "boolean",
            "description": "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.",
            "default": false
          },
          "freeShippingOnly": {
            "title": "Free domestic shipping only",
            "type": "boolean",
            "description": "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.",
            "default": false
          },
          "prefectureCode": {
            "title": "Ships from prefecture (auctions)",
            "type": "array",
            "description": "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`.",
            "default": []
          },
          "endingWithinMinutes": {
            "title": "Ending within N minutes (auctions)",
            "minimum": 1,
            "maximum": 10080,
            "type": "integer",
            "description": "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": {
            "title": "Minimum bids (auctions)",
            "minimum": 0,
            "type": "integer",
            "description": "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": {
            "title": "Sort by",
            "enum": [
              "relevance",
              "endTime",
              "priceLow",
              "priceHigh",
              "buyNowLow",
              "buyNowHigh",
              "bidCount",
              "watchCount"
            ],
            "type": "string",
            "description": "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'.",
            "default": "relevance"
          },
          "fetchItemDetails": {
            "title": "Fetch item details",
            "type": "boolean",
            "description": "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.",
            "default": false
          },
          "autoRetryKeywordMapping": {
            "title": "Retry zero-result Chinese keywords in Japanese",
            "type": "boolean",
            "description": "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.",
            "default": true
          },
          "maxScannedPerSearch": {
            "title": "Max scanned per search",
            "minimum": 100,
            "maximum": 20000,
            "type": "integer",
            "description": "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.",
            "default": 1000
          },
          "maxTotalItems": {
            "title": "Max items for the whole run",
            "minimum": 1,
            "maximum": 50000,
            "type": "integer",
            "description": "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.",
            "default": 1000
          },
          "proxyConfiguration": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "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.",
            "default": {
              "useApifyProxy": false
            }
          }
        }
      },
      "runsResponseSchema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "actId": {
                "type": "string"
              },
              "userId": {
                "type": "string"
              },
              "startedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "finishedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "status": {
                "type": "string",
                "example": "READY"
              },
              "meta": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "example": "API"
                  },
                  "userAgent": {
                    "type": "string"
                  }
                }
              },
              "stats": {
                "type": "object",
                "properties": {
                  "inputBodyLen": {
                    "type": "integer",
                    "example": 2000
                  },
                  "rebootCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "restartCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "resurrectCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "computeUnits": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "options": {
                "type": "object",
                "properties": {
                  "build": {
                    "type": "string",
                    "example": "latest"
                  },
                  "timeoutSecs": {
                    "type": "integer",
                    "example": 300
                  },
                  "memoryMbytes": {
                    "type": "integer",
                    "example": 1024
                  },
                  "diskMbytes": {
                    "type": "integer",
                    "example": 2048
                  }
                }
              },
              "buildId": {
                "type": "string"
              },
              "defaultKeyValueStoreId": {
                "type": "string"
              },
              "defaultDatasetId": {
                "type": "string"
              },
              "defaultRequestQueueId": {
                "type": "string"
              },
              "buildNumber": {
                "type": "string",
                "example": "1.0.0"
              },
              "containerUrl": {
                "type": "string"
              },
              "usage": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "integer",
                    "example": 1
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "usageTotalUsd": {
                "type": "number",
                "example": 0.00005
              },
              "usageUsd": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "number",
                    "example": 0.00005
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}